Errors

Standard error shape

Every non-2xx response returns JSON with at least an error message and a request_id:

{
  "error": "Model not found: gpt-5",
  "request_id": "a1b2c3d4-e29b-41d4-a716-446655440000"
}

The same ID is returned on the x-request-idresponse header. Include it in any Servada support request — it's all that's needed to look up the call.

HTTP status codes

400Bad Request

Malformed request that the gateway can’t process — e.g. a missing file upload, a body that isn’t valid JSON, or an unsupported state for the endpoint.

422Unprocessable Entity

Request shape was understood but a field failed validation. Body uses a messages array with per-field field, message and rule entries. Also used by processor rejections (see below).

401Unauthorized

Missing, malformed or expired token.

403Forbidden

Token lacks the required scope, source IP is not on the allowlist, or a processor requires a scope your token doesn’t have.

402Payment Required

Monthly billing cap reached. See Billing for the body shape and how the cap is computed.

404Not Found

Resource or service not configured (e.g. the model you requested doesn’t exist, or the org hasn’t enabled the scope).

429Too Many Requests

Rate or concurrency limit exceeded. See Rate Limits for the body shapes.

500Internal Server Error

Upstream provider failed, or a processor crashed. Body includes details.

Service failure (5xx)

When a call couldn't complete — an underlying service was unreachable, or a provider returned an error — the response carries a short explanation. Dispatch failures also identify which upstream blew up, so an org admin can correlate it with the upstream tab in the portal:

{
  "error": "Upstream request failed",
  "message": "Connection refused",
  "upstream": { "name": "openai-prod" },
  "hint": "dispatch to upstream \"openai-prod\" failed: Connection refused",
  "request_id": "..."
}

The upstream's base URL and API format stay server-side. Include the request_id if you need to follow up with Servada support.

Request timeouts

A request that runs too long is aborted with an upstream_timeout502. Each upstream has a wall-clock timeout you can tune in the portal's upstream settings (request_timeout_ms). It governs non-streaming completions and the audio / PII / language services; when left blank it inherits the template default, and otherwise a per-service default applies. A value set on an upstream wins over its template.

Streaming completions are bounded differently: an idle timer (reset on every chunk, so a long-but-progressing stream is never cut) plus an absolute hard-max ceiling that caps runaway tool-loops. Both the idle window and the hard-max are gateway-wide settings (STREAM_IDLE_TIMEOUT_MS, REQUEST_HARD_MAX_MS); the per-upstream value also can't exceed the hard-max.

Processor failure

If a processor couldn't run — for example the scope it depends on is unavailable — the completion is rejected with a 500 and the failing processor is identified:

{
  "error": "Processor failed",
  "message": "PII service unavailable",
  "processor": "anonymise",
  "request_id": "..."
}

Validation errors (422)

When a request body or query parameter fails validation — wrong type, missing required field, value out of range — the gateway returns a 422 with a structured messages array. Each entry names the field, a human-readable message, and the rule that failed:

{
  "error": "Validation failed",
  "messages": [
    { "message": "The prompt field must not be greater than 896 characters", "field": "prompt", "rule": "maxLength" },
    { "message": "The year_month field format is invalid", "field": "year_month", "rule": "regex" }
  ],
  "request_id": "..."
}

Processor rejections (422)

Some processors block the request as a matter of policy rather than failing — for example pii_guard rejecting on detected PII, require_local rejecting cloud routes, or prompt_shield rejecting suspected prompt-injection. These return HTTP 422 with a structured request_blocked body that names the processor and a machine-readable reason. Per-processor rejection shapes (and the alternative action: "respond" path some processors offer) are documented on the Processors guide.

Authentication & scope errors

Common 401 / 403 shapes:

{ "error": "Unauthorized", "request_id": "..." }

{ "error": "Token does not have scope: completions", "request_id": "..." }

{ "error": "Processor \"anonymise\" requires scope \"pii\"", "request_id": "..." }

{ "error": "Source IP not allowed for this token", "request_id": "..." }

Contacting Servada support

Every error response contains a request_id, and every successful response carries one on the x-request-idheader. If something isn't working the way you expect, include that ID when you reach out to Servada support — it's all that's needed to trace the call.