Error Handling

All error responses follow a consistent shape: { ok: false, error: 'error_code' }. The error field contains a machine-readable error code. Some endpoints may include additional fields like 'detail' in development mode.

unauthorized — Missing, invalid, or revoked API key (401). rate_limited — Too many requests (429). invalid_json — Malformed request body (400). internal_error — Server-side failure (500). invalid_org — Invalid organization ID (400). forbidden — Insufficient permissions (403).

200 — Success. 400 — Bad request (invalid input). 401 — Unauthorized (auth required). 403 — Forbidden (insufficient permissions). 422 — Unprocessable (validation failed). 429 — Rate limited. 500 — Internal server error. 501 — Not configured. 502 — Upstream error.

Getting 401? Verify your API key is correct and not revoked. Check the Authorization header format. Getting 429? Implement backoff and reduce request frequency. Getting 500? This is a server-side issue — retry after a brief pause and contact support if persistent.