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 value appears in the x-request-id response header. Record it in logs and include it in support requests.

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.

401Unauthorized

Missing, malformed or expired token.

402Payment Required

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

403Forbidden

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

404Not Found

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

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). Decisions also returns 422 with type decision_answer_rejected when Inferada rejects a model’s answer; unlike other 422s, that request is charged when the provider reported usage.

429Too Many Requests

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

500Internal Server Error

An internal gateway or processor failure prevented the request from completing.

502Bad Gateway

An upstream service failed, timed out, or returned an unusable response.

Service failure (5xx)

When a call couldn't complete because an underlying service was unreachable or a provider returned an error, the response includes a short explanation. Dispatch failures can also identify the upstream so an organisation administrator can correlate the failure 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

The gateway aborts a request that runs too long and returns an upstream_timeout 502. 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; leave it blank to use the template's default.

Streaming completions use an idle timer that resets on each chunk and an absolute ceiling for the complete request. Servada manages both platform-wide settings, and an upstream timeout cannot exceed the ceiling.

Processor failure

If a processor couldn't run, for example because the scope it depends on is unavailable, the gateway rejects the completion with a 500 and identifies the failing processor:

{
  "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: pii_guard rejects on detected PII, require_local rejects cloud routes, and prompt_shield rejects 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 includes one in the x-request-id header. Include that value when contacting Servada support.