Errors
Every refusal carries a stable code you can branch on.
Errors
Most refusals return a JSON detail object carrying a stable code and a human-readable message — branch on code where one is given. A few (402, and some 404s) return detail as a plain string instead.
| Status | Code | When |
|---|---|---|
| 401 | invalid_api_key | The key is unknown or malformed. |
| 401 | revoked_api_key | The key was revoked. Generate a new one, or rotate it. |
| 402 | — | The account cannot pay for this run, options included. Nothing runs, nothing is stored and nothing is charged — top up and send the request again. |
| 403 | api_key_tool_not_allowed | The key is not granted this tool. Re-scope the key, or use one that already has it. |
| 403 | api_key_not_permitted_here | Keys authenticate the tool endpoints only. Account, billing, webhook and key management need a signed-in session. |
| 403 | account_disabled | The account this key belongs to is disabled. |
| 403 | max_usage_reached | A free account has reached this tool's lifetime run limit. |
| 403 | free_tier_page_limit | A free account sent more than 1 page. Over the API the call is refused rather than silently trimmed, so a partial answer is never returned as a whole one. |
| 404 | — | The tool is not currently available, or the run id belongs to another account. |
| 429 | rate_limited | The key's per-minute request limit was exceeded. |