Errors and retries

All failures on the OpenAI-compatible routes use one machine-readable envelope, including legacy /v1/completions:

{
  "error": {
    "message": "This project is archived. Unarchive it in project settings to serve requests.",
    "type": "invalid_request_error",
    "code": "project_archived",
    "param": null
  }
}

There is no top-level FastAPI detail field on this surface. Branch on error.code, not on English message text.

Stable codes

Code	HTTP	Retry-After	Meaning
model_warming	503	yes	Cold or temporarily overloaded capacity. Retry after the supplied delay, bounded by the client.
overloaded	503	yes	Reserved provider-level overload code; current pre-admission overloads are normalized to model_warming.
ambiguous_transport	502	no	Dispatch may have reached the model. Do not blindly retry.
upstream_error	502	no	The serving endpoint failed after admission.
model_not_supported	400	no	The base model was never in this deployment's catalog.
model_deprecated	410	no	The base used by a request or fine-tune is retired. Retrain on the current catalog.
model_not_found	404	no	A well-formed alias or training-job reference does not resolve for this caller.
invalid_request	400, 413, or 422	no	The request is malformed, missing a model, or exceeds a context bound.
insufficient_credits	402	no	The account cannot pay for this request or is not entitled to the model.
authentication_error	401	no	The bearer was verified but no ReOpenly account backs it.
project_archived	404	no	The project is reversible but read-only until an owner unarchives it.
internal_error	500	no	An unexpected server failure. Contact support with the request trace if present.

model_deprecated is permanent for that base: production retired the 0.8B, 2B, and 4B catalog entries after the 9B cutover. Retired artifacts remain downloadable, but serving and publishing a retired-base alias are blocked.

Retry policy

Only retry a request automatically when the response explicitly carries Retry-After. Today that is the model_warming path. Use a bounded attempt count and preserve the original request identity. The first-party v2 playground uses at most three automatic retries after the original request, then keeps a manual Retry action available. It never retries a mid-stream error.

Never automatically retry:

• ambiguous_transport, because the model may already have served and billing may already be recorded;
• upstream_error, because admission already happened;
• insufficient_credits, model_deprecated, and project_archived, because changing account/project state is required;
• deterministic invalid_request failures.

Streaming failures

Before the first SSE frame, errors use the normal HTTP status and JSON body. After the stream begins, a mid-stream failure is sent as:

data: {"error":{"message":"…","type":"api_error","code":"upstream_error","param":null}}

The server then closes the stream without sending data: [DONE]. Treat the absence of [DONE] as incomplete output, not as a successful empty response.