Guide
Errors
The ORN API error taxonomy: every error code, its HTTP status, when it happens, and how to correlate errors with your request id.
The error envelope
Errors are JSON with a stable code, a human-readable error message and — where relevant — details. Every error response also carries an x-request-id header and a request_id field with the same value: quote it when contacting support.
{
"code": "INSUFFICIENT_API_WALLET",
"error": "Insufficient API wallet balance for this operation.",
"details": { "required_amount_kobo": 25000 },
"request_id": "3d2a…"
}Error codes
| Code | HTTP | When it happens |
|---|---|---|
| INVALID_REQUEST | 400 | A parameter is missing or malformed — for example a journey_id that is not a UUID. |
| UNAUTHORIZED | 401 | No key, an invalid key, a revoked/expired credential, an inactive application or organization, or an environment mismatch. |
| FORBIDDEN | 403 | The action is not allowed for this key — notably write operations attempted with a sandbox key. |
| CAPABILITY_NOT_AUTHORIZED | 403 | The operation’s required scope or subscription is not granted to your application or organization. |
| INSUFFICIENT_API_WALLET | 402 | The wallet balance cannot cover the operation price. details.required_amount_kobo names the price. |
| FREE_ALLOWANCE_EXHAUSTED | 402 | The free allowance for this capability is used up and the wallet cannot be charged. |
| RESOURCE_NOT_FOUND | 404 | The requested record does not exist in the data visible to your organization — records owned by others are indistinguishable from missing ones. |
| CONFLICT | 409 | The request collides with the record’s current state — for example updating a journey that is no longer draft or planned. |
| RATE_LIMITED | 429 | Too many requests for your rate limit class. Slow down and retry with backoff. |
| INTERNAL_ERROR | 500 | An unexpected server-side failure. Server errors on charged operations are reversed automatically (see Pricing). |
| DEPENDENCY_FAILURE | 502 | A downstream dependency failed while serving the request. |
| ORION_UNAVAILABLE | 503 | The ORION intelligence layer is temporarily unavailable. |
| ROUTING_UNAVAILABLE | 503 | The routing engine is temporarily unavailable. |
Operation-specific errors are documented on each operation’s reference page in API Operations. The table above is the complete global taxonomy: any error not in it is collapsed to INTERNAL_ERROR before it leaves the server, with the unexpected detail logged server-side only.
Retrying safely
- 429 RATE_LIMITED — retry with exponential backoff; respect your rate limit class (see Rate Limits).
- 5xx and network failures — safe to retry; reads are side-effect free, and a charged write that fails on the server is reversed, so a retry is a fresh, correctly-priced attempt.
- 4xx — do not retry blindly; fix the request. 402 errors need wallet attention (see Wallet).
- Always correlate using request_id from the body or x-request-id from the headers.