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 support request — it's all we need to look up the call on our side.

HTTP status codes

400Bad Request

Invalid body or query parameter. The error message describes which field failed validation.

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:

{
  "error": "Upstream request failed",
  "message": "Connection refused",
  "request_id": "..."
}

Include the request_id if you need to follow up with support.

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": "..."
}

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 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 — it's all we need to trace what happened.