Errors

routeur.ai returns short, JSON-shaped errors with a stable error.code and a human-readable error.message. Raw upstream provider error bodies are never relayed to callers — you'll always see a routeur.ai-shaped envelope.

Error shape

response body

{
  "error": {
    "code":    "blocked_by_dlp",
    "message": "dlp:credit_card_redact",
    "type":    "routeur_error"
  }
}

Status & codes

400invalid_request

Malformed JSON or missing required fields such as messages.

401unauthorized

Missing or unknown routeur.ai bearer token. See Authentication.

400embeddings_unsupported

The resolved model does not support embeddings.

402billing_inactive

The organisation's subscription is cancelled. See Limits and quotas.

403blocked_by_dlp

DLP blocked the request before the upstream call. The matching rule slug is in error.message.

403blocked_by_shield

A prompt-shield rule matched the input — for example an instruction-override or encoded-payload attempt.

403blocked_by_classifier

A classifier rule's score threshold was exceeded on the input.

403blocked_by_moderation

The upstream model answered but output moderation blocked the response from reaching the caller.

404model_not_found

Unknown model id, or a model not activated for your workspace.

413body_too_large

Request body exceeded the cap — 5 MiB for chat completions, 10 MiB for embeddings.

429allowance_exceeded

Monthly allowance and overage guardrail both reached. See Limits and quotas.

429upstream_rate_limited

The upstream provider rate-limited the call. Retry with backoff.

502provider_unconfigured

No credential is configured for the resolved provider.

502provider_unavailable

The upstream provider could not be reached.

502upstream_error

Non-timeout upstream failure.

503overloaded

The gateway's in-flight cap was reached. Carries Retry-After; retry with jittered backoff.

504upstream_error

The upstream call hit routeur.ai's per-request timeout. Safe to retry idempotently.

There is no rate_limited code and no forbidden code. A revoked key returns 401 unauthorized, the same as an unknown one.

Errors during a stream

For streamed requests ("stream": true) the HTTP status is committed once the first chunk is sent. A failure after that point cannot change the status, so it arrives as a terminal SSE event and the stream then closes:

event: error
data: {"error":{"code":"upstream_error","message":"...","type":"routeur_error"},"request_id":"01K..."}

A failure before the first chunk (auth, routing, output-moderation block on a moderated org, or an upstream that produced no bytes) is returned as the ordinary JSON error above with its normal status code — no stream is opened.

Two stream-specific cases to handle client-side:

Mid-stream error event. Treat it like the equivalent HTTP error code: upstream_error is retryable, a moderation block is not.
Truncated stream (no terminal error and no [DONE]). A deploy or scale-in can cut a long-lived stream. This is expected operationally; retry the request idempotently.

Retry guidance

Retry: 429, 502, 504 with exponential backoff; a mid-stream upstream_error event; a truncated stream.
Do not retry: 400, 401, 403. The request will keep failing.

← Authentication

Limits and quotas →