Skip to content

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.

ProductCodeMessageDetails
LEO family, envelopecontext.error.codecontext.error.messagecontext.error.details
LEO family, /models and /chat/completionserror.codeerror.messageerror.details
IRMAerrormessagedetails
ORDOerrormessagedetails

In the LEO family an error is a normal envelope with data: null. This response comes from production:

Terminal window
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.

HTTPCodeMeaning
401missing_api_keyNo Authorization header
401invalid_api_keyUnknown or invalid key
401api_key_revokedThe key was revoked
401api_key_expiredThe key expired
401key_environment_mismatchA live key on staging, or a test key on production
403insufficient_scopeThe scope is missing; see details.required_scope
403ip_not_allowedThis IP address is not on the key’s list
403chat_requires_user_tokenChat asks for a user token, not a service key
403approval_requiredAn approval is needed
403forbidden_for_agentsOnly a person in the app
404unknown_operationThis operation does not exist (or is not on this environment yet)
409idempotency_request_in_progressThe same Idempotency-Key is still running
422idempotency_key_reusedThe same Idempotency-Key with a different body
422validation_errorAn invalid value
422scope_not_availableThis scope cannot be issued yet
429rate_limitedLimit reached; follow Retry-After
503service_unavailableTemporarily unavailable; follow Retry-After

The full list per operation is in the reference, under Responses.

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.