Errors - Protégé

Errors use standard HTTP status codes and a consistent body.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_task_name",
    "message": "task must match ^[a-z0-9_-]{1,64}$",
    "param": "task"
  }
}

string

Broad category: invalid_request_error, authentication_error, rate_limit_error, api_error or upstream_error.

string

Specific machine-readable cause. Branch on this, not on the message.

string

Human-readable explanation. Wording may change; do not parse it.

string

The offending request field, when the error is attributable to one.

Status codes

Status	Type	Meaning	Retry
`400`	`invalid_request_error`	Malformed body, bad `task` name, unknown `model`	No, fix the request
`401`	`authentication_error`	Missing or invalid key (`invalid_api_key`)	No
`402`	`insufficient_credit`	Account balance below the minimum to start a request	No, top up
`403`	`authentication_error`	Key lacks access to the requested model or task	No
`404`	`invalid_request_error`	Unknown path or task ID	No
`413`	`invalid_request_error`	Body or context exceeds the route’s limit	No, shorten the input
`429`	`rate_limit_error`	Rate or spend limit exhausted	Yes, after the reset header
`500`	`api_error`	Fault on our side	Yes, with backoff
`502` `503`	`upstream_error`	The routed provider failed or timed out	Yes, with backoff

Retrying

Retry 429, 500, 502 and 503. Do not retry 4xx other than 429, since the same request will fail the same way. Use exponential backoff with jitter, and respect x-ratelimit-reset-requests on a 429 rather than guessing an interval.

import time, random
from openai import APIStatusError

def with_retries(fn, attempts=4):
    for i in range(attempts):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 502, 503) or i == attempts - 1:
                raise
            reset = e.response.headers.get("x-ratelimit-reset-requests")
            delay = float(reset) if reset else (2 ** i) + random.random()
            time.sleep(delay)

Retrying a completion bills again. Cap attempts, and make sure a retry loop around a streaming call does not silently double a long generation’s cost.

Upstream failures

A 502 or 503 carries upstream_unavailable: the provider behind the model failed. Protégé does not silently substitute a different model, because a substitution you did not ask for is a quality change you did not approve. Include x-request-id from the failed response when reporting it.

​Status codes

​Retrying

​Upstream failures

Status codes

Retrying

Upstream failures