Errors

Understand Webway error responses, status codes, and safe retry behavior.

Errors use a small JSON envelope that OpenAI-compatible SDKs can parse:

json

{
  "error": {
    "message": "insufficient credit",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

type is the coarse value client libraries switch on. code is more precise, and differs from type only when a provider is the thing that failed.

The envelope follows the endpoint. /v1/messages returns Anthropic's shape, so Anthropic SDKs and Claude Code parse it and apply their own retry logic without special-casing this gateway:

json

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "the provider is over capacity, retry shortly (request 4f2ab910)",
    "code": "overloaded"
  }
}

Status codes

Status	Meaning	Retry?
`400`	Invalid JSON, fields, or parameters	No; fix the request
`401`	Missing, invalid, expired, or revoked key	No; replace the key
`402`	Your balance cannot cover the request	After adding credit
`403`	The model requires your own provider key	No; add one in the dashboard
`404`	Model or endpoint not found	No; check the ID and path
`413`	Request body is too large	No; reduce the payload
`429`	Rate limit reached	Yes; wait and retry
`502` / `503`	Provider is unavailable	Yes; use backoff
`504`	Provider timed out	Yes; use backoff

402 is only ever about your balance. A billing problem between Webway and a provider is a 502, because it is not something you can act on.

Provider failures

When the failure comes from a provider rather than from your request, code names which one it was:

`code`	Status	Meaning	Retry?
`model_unavailable`	`502`	The provider will not serve this model. Ours to fix	No
`context_length_exceeded`	`400`	The request is longer than the model's context window	No
`content_filtered`	`400`	The provider's safety layer refused	No
`invalid_request`	`400`	The provider rejected the request	No
`rate_limited`	`429`	Rate limited at the provider	Yes
`overloaded`	`503`	The provider is over capacity	Yes
`timeout`	`504`	The provider did not respond in time	Yes
`transport_error`	`502`	The connection to the provider failed	Yes
`upstream_error`	`502`	Unclassified. Always investigated	Maybe

Provider error text is never passed through. Upstreams describe failures in their own vocabulary, sometimes in another language, often naming infrastructure that is not yours, and that text changes without notice. Every one is classified into the set above and rewritten, so the message you get is stable enough to log against.

Each message ends with a Webway request ID. Quote it in support requests: it is the identifier that can actually be looked up.

Errors during streaming

A request can fail after the response headers are already sent. There is no status code left to change at that point, so the failure arrives as an event in the stream, in the same protocol as the rest of it — event: error on /v1/messages, an error event on /v1/responses, an error chunk on /v1/chat/completions. The code values are the same table.

Treat a stream that ends without its terminal event as a failure, not as a short answer.

Retry rules

Retry only 429 and transient 5xx responses. Use exponential backoff with jitter, cap the number of attempts, and honor Retry-After when it is present.

Do not retry 400, 401, 402, 403, 404, or 413 unchanged. The same request will fail again.

Requests rejected before provider work starts are not charged. A request that fails after generation begins can be charged for the tokens already produced, including one you cancel mid-stream.