Operations
Errors
HTTP status codes, normalized error payloads, and practical retry guidance.
HTTP
HTTP status codes
The API uses standard HTTP status codes and returns a normalized JSON error envelope for failures.
| Status | Meaning | Retry? |
|---|---|---|
| 401 | The API key is missing or invalid. | No |
| 403 | The organization is not entitled to API access. | No |
| 409 | The idempotency key was reused with a different payload. | No |
| 422 | The request payload violated a contract rule. | No |
| 429 | The per-key, per-org, or per-IP limit was exceeded. | Yes |
| 500 | A server-side issue prevented the request from completing. | Yes |
Payload
Common error codes
Each error payload includes a machine-readable `code`, a human-readable `message`, a `retryable` flag, and sometimes `retry_after`.
| Code | When it appears |
|---|---|
| unauthorized | The API key is missing or invalid. |
| forbidden | The organization is not entitled to API access. |
| idempotency_conflict | The idempotency key was reused with a different payload. |
| validation_error | The request payload violated a contract rule. |
| rate_limited | The per-key, per-org, or per-IP limit was exceeded. |
| internal_error | A server-side issue prevented the request from completing. |
Handling
Handling failures
Treat authentication and validation failures as terminal. Retry only rate limits and transient server failures.
Terminal vs retryable
- 401, 403, 409, and 422 are client errors. Fix the request or access model before sending it again.
- 429 means you are temporarily throttled. Respect the advertised retry window.
- 500 means the server failed. Retry with backoff and keep the same idempotency key if the request was a write.