plaingateway
API reference

Errors

Error bodies, every status the gateway returns, and what to do about each.

Every endpoint except /messages returns errors in this shape. error.code is the HTTP status, not a provider code.

json
{
  "error": {
    "message": "No endpoints found matching your provider.only list",
    "code": 404,
    "metadata": { "routing_funnel": [], "failed_routing_step": "Filter by Only" }
  },
  "user_id": "10000000-0000-0000-0000-000000000001"
}

metadata is present only when there is detail: provider_name on a host error, routing_funnel and failed_routing_step when routing filters leave no host. user_id (your account id) is sent on 400 answers once the key is known. /messages uses Anthropic's shape: {"type": "error", "error": {"type": "authentication_error", "message": "...", "error_type": "authentication"}, "request_id": null}.

Statuses

Status Cause What to do Charged
400 Invalid JSON, no input, a missing or unknown model id, an unsupported variant, a bad provider object, plugins or transforms set, or a request no host can take Fix the request No
401 No key, or a key that is unknown, disabled, expired or revoked Send a valid key No
402 The balance cannot cover this request, or the key reached its spend limit Top up at /settings/credits, or raise the key's limit No
404 Unknown path, unknown generation id, unknown model on /endpoints, or no host left after routing filters Check the id, or relax the provider filters No
408 The host sent no answer in time Retry No
413 The request body is over 32 MiB Send a smaller body No
429 The last host tried rate limited the request Wait for Retry-After when present, then retry No
500 A catalog entry could not be read Retry later No
502 The host returned an error, or a response cut off, unreadable or over 32 MB Retry; the message carries the request id See below
503 The gateway's key, billing or usage store is briefly unavailable Retry after a short wait No

A host's own 4xx answer, such as a context length error, keeps its status. The message is Provider returned error, and metadata.raw carries the host's body. A host's 401 or 403 means the host refused the gateway's credentials, so you get 502. An error answered before the host produced output is not charged. A 502 for a response the host did finish, but that was over 32 MB or could not be translated, can be charged for the tokens the host reported. Usage accounting explains charges. Before answering 408, 429 or 502 for a host that failed, timed out or rate limited, the gateway tries the next eligible host; see Rate limits. A 502 for a response that arrived but was unreadable comes back at once, without trying another host. With Allow fallbacks off in your account settings, the gateway tries one host per model.

Errors inside a stream

Once a stream has started, the status is already 200, so a failure arrives as a last event with the error body and metadata.provider_name, and the stream ends. Its error.code is 408 for a timeout and 502 otherwise.

Example

Request

sh
curl https://api.plaingateway.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-pg-v1-not-a-real-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-5.6-luna", "messages": [{"role": "user", "content": "Say hello in five words."}]}'

Response

http
HTTP/1.1 401
{
  "error": {
    "message": "User not found.",
    "code": 401
  }
}