§.Public API & SDK
Error codes and handling
Every error code the public API returns, what causes it, and how to recover.
Updated 2026-04-13
Every error response uses the shape { error: { code, message } }. code is a stable UPPER_SNAKE_CASE identifier you can switch on in your client; message is a human-readable explanation that may change.
| HTTP | code | Meaning | Recovery |
|---|---|---|---|
| 400 | INVALID_PARAM | Query param or body failed validation (e.g. non-UUID id, bad page). | Fix the request shape per the message. |
| 401 | UNAUTHORIZED | Missing/malformed Authorization header, revoked key, or the key's owner requires a password reset. | Set a valid Bearer token. If your account requires password reset, log in to the web app first. |
| 402 | DISPUTED | The workspace's subscription has an active chargeback dispute. All API calls are blocked until resolved. | Resolve the dispute in the Stripe Customer Portal, then retry. |
| 402 | PAST_DUE | The workspace's subscription is past-due or over its limit. API calls are blocked until payment is updated. | Open the billing page and update the payment method. |
| 403 | API_NOT_ALLOWED | The workspace is on Free tier. Free does not include public API access. | Upgrade the workspace to Solo or higher (/billing). |
| 404 | NOT_FOUND | Prompt / version not found, or in a workspace the key can't see. | Verify the id; check the key's active workspace. |
| 429 | RATE_LIMITED | Per-minute per-key or global rate limit exceeded. | Back off per the Retry-After header. |
| 500 | INTERNAL_ERROR | Unexpected server error. | Log the request id from x-request-id and contact support. |
The public API is read-only — there are no endpoints that trigger LLM calls, so the monthly AI call cap does not apply here. That cap is enforced inside the web UI only.
Related in-app error codes
Some error messages you see in the web UI (e.g., seat-cap errors when inviting members, or ownership-transfer limits) are not returned by the public API. They only appear in the app's own workflows. If you're using the SDK, you'll only encounter the error codes listed in the table above.
Retrying
- 429 — exponential backoff honouring
Retry-After. - 5xx — exponential backoff with jitter, max 3 retries.
- 4xx other than 429 — do not retry; the request is malformed.