Router.Africa — API Error Catalogue
Every error api.router.africa returns: the body shape, status codes, headers, and what a client should do. Written for task P1.08. It implements the decisions log entry API error contract and response extras; where they disagree, the decisions log wins.
This is a contract. apps/api must emit exactly these errors, the curated OpenAPI spec (Track D, D.06) describes them, and the developer docs publish them. Adding a reason is a decision; renaming or removing one is a breaking change.
1. Body shape
Section titled “1. Body shape”OpenRouter’s envelope, so client code ported from OpenRouter keeps working, with only the error types we actually emit:
{ "error": { "code": 402, "message": "This workspace doesn't have enough credits for this request. Add credits at https://app.router.africa.", "metadata": { "error_type": "payment_required", "reason": "insufficient_credits" } }}| Field | Meaning |
|---|---|
error.code |
The HTTP status, as a number (OpenRouter’s convention) |
error.message |
Human-readable, safe to show. Never contains a full key, a provider name, gateway details, or prompt content |
error.metadata.error_type |
The portable category, from OpenRouter’s error_type vocabulary (section 3). Branch on this for retry logic |
error.metadata.reason |
Our specific cause, e.g. insufficient_credits versus key_spend_cap_exceeded, which share payment_required. Branch on this for user-facing handling |
error.metadata.* |
Optional extra fields listed per reason below (e.g. model on model_not_found). Nothing else |
OpenAI SDK compatibility. OpenAI’s SDKs pick the exception class from the HTTP status and read error.message, so they work unchanged; error.code is a number rather than OpenAI’s string, as with OpenRouter. This replaces the OpenAI-style type and string code proposed in auth-security.md 2.3.
Never in an error: the provider or gateway’s own message or status (mapped, section 5), a stack trace, any header value, any part of the prompt or response.
2. Headers
Section titled “2. Headers”| Header | When |
|---|---|
x-request-id |
On every response, success or error. Our request id: the same one in the request log and sent to the gateway, so support requests line up |
WWW-Authenticate: Bearer realm="router.africa" |
On every 401 |
Retry-After (seconds) |
Always on 429, 503 and 529. The value is the gateway’s when it gives one, else the edge block time for edge_rate_limited, else the default of 5 seconds (a small constant: the API doesn’t know the org’s rate-limit window at that point, and 5 s is long enough not to invite a retry loop yet short enough not to stall a client on a one-off limit) |
x-idempotent-replay: true |
A Router.Africa extension, not part of OpenAI’s or OpenRouter’s API. Sent only when the response is a stored replay of an earlier identical request (same body, or same Idempotency-Key, see the decisions log, Idempotency key design) rather than a new run. A replay isn’t charged again. Absent on a new run |
x-ratelimit-* |
Not sent. Rate limits are set per org and are not shown to customers (decisions log, Rate limiting / abuse prevention). Clients back off on 429 using Retry-After |
3. Catalogue
Section titled “3. Catalogue”error_type values come from OpenRouter’s taxonomy (openrouter-api-comparison.md 1.4); we emit only the ones in this table.
| Status | error_type |
reason |
When | Message (template) | Client should |
|---|---|---|---|---|---|
| 400 | invalid_request |
invalid_body |
Body isn’t valid JSON or fails validation | Request body is invalid: <detail>. |
Fix the request |
| 400 | invalid_request |
key_not_in_header |
A key was sent in the query string or body (auth-security.md 2.1) |
Send your API key in the Authorization header, not the URL or body. | Move the key to the header; consider rotating it |
| 400 | context_length_exceeded |
context_length_exceeded |
The provider rejects the prompt as too long | The request is too long for <model>’s context window. Shorten the input and retry. |
Shorten the input |
| 401 | authentication |
missing_api_key |
No Authorization header, or not Bearer (on POST /v1/messages, also no x-api-key) |
You didn’t provide an API key. Send it as Authorization: Bearer YOUR_KEY. |
Add the header |
| 401 | authentication |
invalid_api_key |
Key unknown, malformed, revoked, expired or still pending; one answer for all of them |
Incorrect API key provided: sk-ra-…abcd. Check your keys at https://app.router.africa. |
Use a valid key. Don’t retry |
| 402 | payment_required |
insufficient_credits |
Available credits (balance minus held) are below the minimum hold, or below what the request needs | This workspace doesn’t have enough credits for this request. Add credits at https://app.router.africa. | Top up. Don’t retry until then |
| 402 | payment_required |
key_spend_cap_exceeded |
The key’s spend cap is reached: the user cap (Postgres) or the admin cap (gateway budget). One answer for both | This API key has reached its spend limit. Raise the limit or use another key. | Raise the cap, wait for the cap period to reset, or switch keys |
| 403 | permission_denied |
account_suspended |
The org is suspended, or the workspace is frozen or deleted (decisions log, Org suspension) | This account is suspended. Contact support. | Contact support. Don’t retry |
| 403 | content_policy_violation |
content_policy_violation |
The provider refuses the content | The request was blocked by the model provider’s content policy. | Change the content |
| 404 | not_found |
model_not_found |
Model unknown, off, or not allowed for this key; one answer for all three | The model <model> does not exist or you do not have access to it. |
Check the model id and the key’s allowed models. metadata.model = what was sent |
| 404 | not_found |
route_not_found |
Unknown path or method | No such endpoint. Check the URL and method. | Check the endpoint |
| 409 | invalid_request |
request_in_progress |
An identical request (same body, or same Idempotency-Key) is still running |
An identical request is already in progress. | Wait and retry; the first request’s result will be returned |
| 413 | payload_too_large |
payload_too_large |
Body over the 16 MiB limit, checked before buffering (auth-security.md 2.1) |
The request body is too large. Send less than 16 MiB. | Send less |
| 429 | rate_limit_exceeded |
rate_limited |
The key’s rate limit (gateway) is hit | Rate limit reached for this API key. Retry after <n> seconds. (<n> is the Retry-After value, always present) |
Back off; honour Retry-After |
| 429 | rate_limit_exceeded |
concurrency_limited |
The org already has organizations.max_in_flight requests running (default 20, across all its workspaces and keys). Checked inside core.claim_and_hold; the claim is rolled back, nothing is held or charged |
Too many requests are running at once for this account. Wait for some to finish, then retry. | Wait for running requests to finish, then retry; honour Retry-After |
| 429 | rate_limit_exceeded |
edge_rate_limited |
The per-IP edge rule at Cloudflare is hit (decisions log, Edge rate limiting), or the client IP has more than 30 rejected key lookups a minute (AUTH_FAILURE_LIMITER, auth-security.md 2.1) |
Too many requests from this address. Retry after <n> seconds. |
Back off; honour Retry-After |
| 408 | timeout |
upstream_timeout |
The gateway gave up after its own retries and fallbacks | The model provider took too long to respond. | Retry with backoff |
| 500 | server |
internal_error |
A bug or misconfiguration on our side (including the gateway rejecting our own credentials) | Something went wrong on our side. Reference: <request id>. |
Retry once; contact support with the request id |
| 502 | provider_unavailable |
provider_error |
The provider returned an error after the gateway’s fallbacks | The model provider returned an error. | Retry with backoff |
| 503 | server |
service_unavailable |
We can’t place the hold (database unreachable); the request is refused before any model is called | The service is temporarily unavailable. | Retry with backoff |
| 529 | provider_overloaded |
provider_overloaded |
The provider is overloaded and fallbacks are exhausted | The model provider is overloaded. Retry shortly. | Retry with backoff |
Why 402 for money, not 429. auth-security.md 2.4 left this open: OpenAI uses 429 for exhausted balance, but OpenAI’s SDKs retry 429s automatically, so “no credits” would be retried pointlessly. OpenRouter uses 402 for insufficient credits, and SDKs don’t retry it. Since we adopted OpenRouter’s envelope, money errors are 402. Flagged for review (decision made while writing the catalogue).
max_tokens is capped, not an error (decided 2026-11-07). A max_tokens (or max_output_tokens) above the model’s ceiling is silently lowered to the ceiling, so there is no max_tokens_above_limit reason. The earlier row and the max_tokens_exceeded type are removed.
Same answer on purpose. invalid_api_key, model_not_found and key_spend_cap_exceeded each cover several causes, so nobody can probe whether a key existed, which models exist, or which cap applies (auth-security.md 2.3).
Edge 429s come from Cloudflare. The rate-limiting rule must be configured with a custom JSON response matching this envelope, including reason: edge_rate_limited (task P8.07 / P9.05), with a Retry-After header and the message Retry after <n> seconds. filled in. x-request-id isn’t available there.
4. Streaming
Section titled “4. Streaming”- An error before the first token is a normal HTTP error response from this catalogue.
- An error after streaming has started can’t change the
200status. It is sent as a final SSE event,data: {"error": {…same envelope…}}, then the stream ends. Settlement uses the gateway’s reported partial usage (decisions log, Mid-stream client disconnect policy).
5. Gateway and provider errors (mapping in the adapter)
Section titled “5. Gateway and provider errors (mapping in the adapter)”The gateway adapter maps every gateway response to this catalogue; nothing gateway-specific passes through.
| Gateway says | We return |
|---|---|
Virtual key rejected (401/403 from the gateway) |
500 internal_error. It’s our credential, not the customer’s; alerts fire |
Budget exceeded (gateway 402, the admin USD cap) |
402 key_spend_cap_exceeded |
Rate limit (gateway 429) |
429 rate_limited, with Retry-After: the gateway’s value, else the 5 s default |
| Model not allowed for the virtual key | 404 model_not_found (also signals config drift; key reconciliation should catch it) |
Provider 400 context-length error |
400 context_length_exceeded |
| Provider content refusal | 403 content_policy_violation |
| Timeout after fallbacks | 408 upstream_timeout |
| Provider overloaded after fallbacks | 529 provider_overloaded |
| Any other provider error after fallbacks | 502 provider_error |
| Anything unrecognised | 500 internal_error, logged with the raw gateway response (never returned) |
Every gateway rejection releases the hold (decisions log, Credit hold/settle mechanism).
7. POST /v1/messages: Anthropic’s error format (decided 2026-11-07)
Section titled “7. POST /v1/messages: Anthropic’s error format (decided 2026-11-07)”Anthropic SDKs parse Anthropic’s error body, so only on POST /v1/messages (and any error that route returns, including auth and route_not_found) the body is:
{ "type": "error", "error": { "type": "authentication_error", "message": "You didn't provide an API key. Send it as `x-api-key: YOUR_KEY` or `Authorization: Bearer YOUR_KEY`.", "reason": "missing_api_key" }}error.type is Anthropic’s type, chosen from the HTTP status (below). error.reason is our specific cause, the same values as metadata.reason in section 3; per-reason extras (e.g. model on model_not_found) sit beside it inside error. message is the same text as section 3. Status codes and headers (x-request-id, WWW-Authenticate, Retry-After, x-idempotent-replay) are unchanged. There is no error.code and no metadata here.
| Status | Anthropic error.type |
Notes |
|---|---|---|
| 400, 409, 413 | invalid_request_error |
Includes invalid_body, key_not_in_header, context_length_exceeded, request_in_progress, payload_too_large |
| 401 | authentication_error |
missing_api_key, invalid_api_key |
| 402 | billing_error |
insufficient_credits, key_spend_cap_exceeded |
| 403 | permission_error |
account_suspended, content_policy_violation |
| 404 | not_found_error |
model_not_found, route_not_found |
| 429 | rate_limit_error |
rate_limited, concurrency_limited, edge_rate_limited; Retry-After always sent |
| 408, 500, 502, 503 | api_error |
upstream_timeout, internal_error, provider_error, service_unavailable |
| 529 | overloaded_error |
provider_overloaded; Retry-After always sent |
Mid-stream errors. After streaming has started the status is already 200, so the error is a final SSE event in Anthropic’s format, then the stream ends:
event: errordata: {"type":"error","error":{"type":"overloaded_error","message":"The model provider is overloaded. Retry shortly.","reason":"provider_overloaded"}}Implementation: errorResponse in apps/api switches to this body for the /v1/messages path; the route (P0.13) must emit the event: error event for mid-stream failures. The edge 429s from Cloudflare (section 3) are not on a path the edge can tell apart and keep the standard envelope.
8. What this changes elsewhere
Section titled “8. What this changes elsewhere”auth-security.md2.3 and 2.4: the OpenAI-styletype/ stringcodeand the open 402-versus-429 question are replaced by this catalogue.api-surface.mdsection 6: the error-format item is complete.POST /v1/messagesfollows section 7 (Anthropic’s format) instead of section 1;POST /v1/responsesuses the section 1 envelope.- Track D: D.06 encodes this in the OpenAPI spec, with an example per row; D.08 writes the Errors page from it.
- Phase 3: P3.01 (adapter mapping), P3.02 (auth errors) and P3.10 (conformance tests) implement it; the conformance suite should assert every row it can trigger.