Errors

All errors return a non-2xx HTTP status and a plain-text response body containing the error message. The HTTP status line also includes the error message for convenience.

Status codes

Status Meaning
401 Missing, malformed, or invalid Bearer token; revoked key; IP not in whitelist
403 API key is read-only and called a write method; endpoint not exposed to API keys; key has no access to the requested workspace
429 Rate limit exceeded (either hourly or per-minute bucket)
500 Validation error, application-level exception, or unexpected failure
503 API access has been disabled on this account

Example

HTTP/1.1 401 Invalid API key
Content-Type: text/plain

Invalid API key

Recommendations

  • Check the HTTP status code first.
  • For 401s, verify the Authorization header is present and the token has not been rotated or deleted.
  • For 403s on workspaces, verify the key's workspace whitelist includes the workspace you're requesting.
  • For 429s, respect Retry-After and back off.
  • For 500s, the body contains the exception message. Common causes: missing required fields, invalid field types, referencing an unknown table ID.