# Errors

Interpret failures without duplicating work or increasing spend.

## Error envelope

Most API failures use the following shape. Some errors omit `code`; inspect the HTTP status and safe `message` as well.

```json
{
  "error": {
    "code": "PRICE_CHANGED",
    "message": "The current price exceeds your requested Gem limit."
  }
}
```

| HTTP | Code | What to do |
| --- | --- | --- |
| 401 | `INVALID_API_KEY` | Check secret format, expiration, and revocation. |
| 403 | `INSUFFICIENT_SCOPE` | Use a key with the required scope. |
| 403 | `ACCOUNT_BLOCKED` / `ACCOUNT_UNAVAILABLE` | Resolve account access or finish account setup. |
| 402 | `API_KEY_LIMIT` | Check cap and outstanding reservations; do not raise the cap automatically. |
| 402 | `LLM_QUOTA_EXHAUSTED` | Check the account's LLM allowance and paid-Gem settings. |
| 409 | `PRICE_CHANGED` | Reduce request cost or obtain approval for a higher ceiling. |
| 409 | `IDEMPOTENCY_CONFLICT` | Restore the original body for this identity; use a new identity only for a distinct authorized request. |
| 409 | `REQUEST_UNCERTAIN` | Keep the original key, body, and identity. Check/replay with backoff; never blindly dispatch a new request. |
| 409 | `REQUEST_FAILED` | The original claim was released. A new authorized generation needs a new identity. |
| 409 | `REFERENCES_PROCESSING` | Keep the same identity and check reference readiness. |
| 409 | `ANALYSIS_FAILED` | Analysis could not be parsed; measured usage may already be billed. |
| 404 | `NOT_FOUND` | Check the route/task ID and ownership. |
| 413 | optional `INVALID_REQUEST` | Reduce payload size. |
| 422 | `INVALID_REQUEST` / `INVALID_REFERENCE` / `MODEL_UNAVAILABLE` | Check fields, references, and discovered models. |
| 503 | `WORKFLOW_UNAVAILABLE` / `PROVIDER_UNAVAILABLE` / `TEMPORARILY_UNAVAILABLE` | Preserve the original request identity and apply backoff. |

Other canonical generation/policy errors can be returned. Do not bypass account restrictions or moderation by rewriting requests or switching keys. Provider failures can leave uncertain reservations; a 5xx is not permission to resubmit with a new identity.

For support, retain safe IDs, status, code, and timestamps. Exclude bearer keys and signed media URLs from logs. For SSE, inspect in-stream errors and require `[DONE]` before reporting a complete text result.