Errors
Every error has three things: a fixed string code to program against, a readable message and, where it adds something, details. Program against the code, never against the message.
Where it is
Section titled “Where it is”| Product | Code | Message | Details |
|---|---|---|---|
| LEO family, envelope | context.error.code | context.error.message | context.error.details |
LEO family, /models and /chat/completions | error.code | error.message | error.details |
| IRMA | error | message | details |
| ORDO | error | message | details |
In the LEO family an error is a normal envelope with data: null. This response comes from production:
curl -s https://api.prudai.com/v1/sources{ "data": null, "context": { "request_id": "req_...", "error": { "message": "A Bearer API key is required.", "type": "authentication_error", "code": "missing_api_key", "param": null, "request_id": "req_..." } }, "completeness": { "total": 0, "returned": 0, "truncated": false }, "notIncluded": [], "provenance": {}, "next": []}/models and /chat/completions keep the OpenAI shape { "error": { ... } }, so the OpenAI SDKs raise their usual errors.
With IRMA and ORDO error itself is the string code:
{ "error": "insufficient_scope", "message": "...", "details": { "required_scope": "..." } }The CLI turns all of these into one shape: { error, message, exitCode, ...details }. See CLI.
Common codes
Section titled “Common codes”| HTTP | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization header |
| 401 | invalid_api_key | Unknown or invalid key |
| 401 | api_key_revoked | The key was revoked |
| 401 | api_key_expired | The key expired |
| 401 | key_environment_mismatch | A live key on staging, or a test key on production |
| 403 | insufficient_scope | The scope is missing; see details.required_scope |
| 403 | ip_not_allowed | This IP address is not on the key’s list |
| 403 | chat_requires_user_token | Chat asks for a user token, not a service key |
| 403 | approval_required | An approval is needed |
| 403 | forbidden_for_agents | Only a person in the app |
| 404 | unknown_operation | This operation does not exist (or is not on this environment yet) |
| 409 | idempotency_request_in_progress | The same Idempotency-Key is still running |
| 422 | idempotency_key_reused | The same Idempotency-Key with a different body |
| 422 | validation_error | An invalid value |
| 422 | scope_not_available | This scope cannot be issued yet |
| 429 | rate_limited | Limit reached; follow Retry-After |
| 503 | service_unavailable | Temporarily unavailable; follow Retry-After |
The full list per operation is in the reference, under Responses.
Retrying
Section titled “Retrying”Every response has an X-Request-Id; quote it to support. Retry on 429 and 503, with increasing waits, and follow Retry-After. Use the same Idempotency-Key for a repeated write.