Error handling

Error codes, retries, and what to do when things break.

Errors before the first byte come as an HTTP status; errors mid-stream come as a frame.

Error envelope

Every error comes in the same shape. details is optional and only set on body validation.

json

{
  "error": {
    "code": "validation_error",
    "message": "The request is invalid.",
    "details": { "fields": [] }
  }
}

validation_error422

Invalid body or parameter, empty or corrupt image file.

unauthorized401

Authentication missing or invalid.

rate_limited429

Provider quota exhausted.

configuration_error500

Misconfiguration, e.g. VISION_ENABLED=false on a vision call.

internal_error500

Unexpected error in the backend.

provider_error502

Upstream returns nothing usable.

provider_timeout504

Upstream is too slow.

On /chat/stream the error does not come as an HTTP status (that is 200 by then) but as an event: error frame with the same error object.