Errors

All errors follow a consistent envelope format with machine-readable codes.

Error Envelope

Every error response returns the same shape:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "status": 400,
    "requestId": "req_a1b2c3d4e5f6a7b8",
    "details": null
  }
}

Error Codes

Validation Errors

When a request fails validation, the details field may contain structured information about which fields failed:

{
  "error": {
    "code": "INVALID_QUERY_PARAMETER",
    "message": "One or more query parameters are invalid.",
    "status": 400,
    "requestId": "req_a1b2c3d4e5f6a7b8",
    "details": {
      "fields": {
        "limit": "Must be an integer between 1 and 100",
        "sort": "Invalid sort field. Allowed: createdAt, updatedAt"
      }
    }
  }
}

Rate Limiting

The API enforces rate limits per 5-minute sliding window:

Rate Limit Headers

Every response includes rate limit headers so you can track your usage:

Rate Limit Example

When you exceed the limit, the API returns 429:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later.",
    "status": 429,
    "requestId": "req_x9y8z7w6v5u4t3s2",
    "details": null
  }
}

Best practices:

1. Check X-RateLimit-Remaining before making requests
2. When you receive a 429, wait for the number of seconds in the Retry-After header
3. Implement exponential backoff for retry logic

Troubleshooting

401 Errors

1. Verify the Authorization header format: Bearer imb_pat_...
2. Check that the token has not expired or been revoked
3. Confirm the token exists in Account > API Access

403 Errors

1. Verify the authenticated user has access to the target board
2. Check billing status if you see BILLING_RESTRICTED
3. ACCOUNT_SUSPENDED and ACCOUNT_INACTIVE indicate account-level issues — contact support

404 Errors

1. Verify the resource ID is correct
2. Confirm the authenticated user has access to the parent board
3. The API returns 404 (not 403) for resources the user cannot access — this prevents leaking resource existence

429 Errors

1. Read the Retry-After header and wait before retrying
2. Check X-RateLimit-Reset to know when your window resets
3. Reduce request frequency or implement request batching where possible