Dashboard

Cookbook Recipe

Error handling

Handle every API error in production

One wrapper, callWithPolicy, that knows what to do with every documented error code: wait, retry, fall back, alert or stop. This client wraps Chat Completions.

POSThttps://api.devupai.com/v1/chat/completions

What you'll build

A single function that sends a chat completion and gives every error code exactly one action class: retry after the delay in the headers, retry with backoff, fall back to another request, or raise a typed PolicyError with the code, the status, the message, the action and the request id. On success it logs the request id next to your own correlation id and alerts you when your balance drops below a threshold you choose.

Before you start

  • Python 3.10 or later with the openai package, or Node.js 22.12 or later with the devupai package.
  • An API key (sk-devup-...) or a Scoped JWT in DEVUP_API_KEY. See Authentication.
  • A model ID from GET /v1/models in DEVUP_MODEL, or as the first argument of the program.
  • Optional: DEVUP_FALLBACK_MODEL, a second model ID for the fallback hook, and LOW_BALANCE_THRESHOLD_DZD, a number in DZD below which a successful call alerts you.
pip install openai
Terminal
export DEVUP_API_KEY=sk-devup-your-api-key
export DEVUP_MODEL="<a model ID from GET /v1/models>"
# Optional
export DEVUP_FALLBACK_MODEL="<a second model ID>"
export LOW_BALANCE_THRESHOLD_DZD="<a number in DZD>"

The complete program

Save it as policy_client.py or policy_client.mjs. The Node.js program uses the official devupai SDK; the Python program uses the openai package with the DEVUP AI base URL. The core functions take their dependencies (client, sleep, now, the random source, alert, fallback) as parameters, so you can test them with a stub client. Calls are non-streaming.

"""A Chat Completions client with one policy for every documented error code."""
import logging
import os
import random
import sys
import time
import uuid
from typing import Any, Callable, Dict, Optional

import openai
from openai import OpenAI

log = logging.getLogger("devup.policy")

RETRY_AFTER = "RETRY_AFTER"
RETRY_BACKOFF = "RETRY_BACKOFF"
FALLBACK = "FALLBACK"
FIX_REQUEST = "FIX_REQUEST"
FIX_CREDENTIALS = "FIX_CREDENTIALS"
NEW_TOKEN = "NEW_TOKEN"
ADD_FUNDS = "ADD_FUNDS"
CONTACT_SUPPORT = "CONTACT_SUPPORT"
DO_NOT_REPLAY = "DO_NOT_REPLAY"

CODE_CLASS = {
    # The request itself needs a change.
    "invalid_request_body": FIX_REQUEST,
    "missing_model": FIX_REQUEST,
    "missing_tools": FIX_REQUEST,
    "invalid_max_tokens": FIX_REQUEST,
    "invalid_value": FIX_REQUEST,
    "missing_required_parameter": FIX_REQUEST,
    "cache_retention_unsupported": FIX_REQUEST,
    "use_responses_api": FIX_REQUEST,
    "wrong_endpoint": FIX_REQUEST,
    "unsupported_parameter": FIX_REQUEST,
    "context_length_exceeded": FIX_REQUEST,
    "invalid_request_format": FIX_REQUEST,
    "empty_message_content": FIX_REQUEST,
    "conversation_must_end_with_user": FIX_REQUEST,
    "structured_output_mismatch": FIX_REQUEST,
    "payload_too_large": FIX_REQUEST,
    "invalid_request_error": FIX_REQUEST,
    "permission_denied": FIX_REQUEST,
    "scoped_budget_unbounded_request": FIX_REQUEST,
    "model_configuration_error": FIX_REQUEST,
    "model_not_found": FIX_REQUEST,
    "model_not_allowed": FIX_REQUEST,
    # The model does not take this request: another model or request may.
    "unsupported_content": FALLBACK,
    "tools_not_supported": FALLBACK,
    "feature_not_supported": FALLBACK,
    "response_format_not_supported": FALLBACK,
    "flex_capacity_unavailable": FALLBACK,
    # The key.
    "invalid_api_key": FIX_CREDENTIALS,
    "missing_api_key": FIX_CREDENTIALS,
    # The Scoped JWT.
    "token_expired": NEW_TOKEN,
    "token_revoked": NEW_TOKEN,
    "budget_exhausted": NEW_TOKEN,
    # The balance.
    "insufficient_balance": ADD_FUNDS,
    # The account or its configuration.
    "account_suspended": CONTACT_SUPPORT,
    "server_configuration_error": CONTACT_SUPPORT,
    "billing_configuration_error": CONTACT_SUPPORT,
    # The outcome of the request is not known yet.
    "request_outcome_pending": DO_NOT_REPLAY,
    # Wait for the delay in the response headers.
    "rate_limit_exceeded": RETRY_AFTER,
    "concurrency_limit_exceeded": RETRY_AFTER,
    "tpm_limit_exceeded": RETRY_AFTER,
    "service_unavailable": RETRY_AFTER,
    "model_at_capacity": RETRY_AFTER,
    "model_unavailable": RETRY_AFTER,
    # Retry with exponential backoff.
    "DEVUP_COMPUTE_ERROR": RETRY_BACKOFF,
}

# Retried after the delay up to CAPACITY_RETRIES times, then handed to the fallback hook.
RETRY_THEN_FALLBACK = {"model_at_capacity", "model_unavailable"}
CAPACITY_RETRIES = 2
MAX_WAIT_SECONDS = 30.0
BACKOFF_BASE_SECONDS = 1.0


class PolicyError(Exception):
    """An error the policy does not retry: code, HTTP status, message, action class, request id."""

    def __init__(
        self,
        code: Optional[str],
        status: Optional[int],
        message: str,
        action: str,
        request_id: Optional[str],
        headers: Any = None,
    ) -> None:
        super().__init__(message)
        self.code = code
        self.status = status
        self.message = message
        self.action = action
        self.request_id = request_id
        self.headers = headers


def is_account_key(api_key: Optional[str]) -> bool:
    """True for an account API key (sk-devup-...); a Scoped JWT is not one. Reads the prefix only."""
    return isinstance(api_key, str) and api_key.startswith("sk-devup-")


def classify(status: Optional[int], code: Optional[str]) -> str:
    """The action class of an error: by its code, else by its HTTP status."""
    if code in CODE_CLASS:
        return CODE_CLASS[code]
    if status == 429:
        return RETRY_AFTER
    if status is None or status >= 500:
        return RETRY_BACKOFF
    return FIX_REQUEST


def retry_delay_seconds(headers: Any) -> float:
    """Seconds to wait: retry-after-ms, then Retry-After; 1 s when missing or not positive."""
    for name, per_second in (("retry-after-ms", 1000.0), ("retry-after", 1.0)):
        value = headers.get(name) if headers is not None else None
        if value is None:
            continue
        try:
            seconds = float(value) / per_second
        except ValueError:
            continue
        return min(seconds, MAX_WAIT_SECONDS) if seconds > 0 else 1.0
    return 1.0


def backoff_seconds(attempt: int) -> float:
    """Exponential backoff: 1 s, 2 s, 4 s, ... capped at MAX_WAIT_SECONDS."""
    return min(BACKOFF_BASE_SECONDS * 2 ** (attempt - 1), MAX_WAIT_SECONDS)


def to_policy_error(exc: openai.APIError) -> PolicyError:
    """Turns an SDK error into a PolicyError with its action class."""
    if isinstance(exc, openai.APIStatusError):
        body = exc.body if isinstance(exc.body, dict) else {}
        message = body.get("message") or exc.message
        error = PolicyError(
            code=exc.code,
            status=exc.status_code,
            message=message,
            action=classify(exc.status_code, exc.code),
            request_id=exc.response.headers.get("x-request-id"),
            headers=exc.response.headers,
        )
    else:
        code = "timeout" if isinstance(exc, openai.APITimeoutError) else "connection_error"
        error = PolicyError(code=code, status=None, message=str(exc), action=RETRY_BACKOFF, request_id=None)
    error.__cause__ = exc
    return error


def check_success(
    completion: Any,
    *,
    alert: Callable[[str, Optional[str]], None],
    correlation_id: Optional[str],
    low_balance_threshold: Optional[float],
    attempts: int,
    elapsed: float,
) -> None:
    """Logs the request id with your correlation id, and alerts when the balance is low."""
    extra = getattr(completion, "model_extra", None) or {}
    devup = extra.get("_devup") or {}
    request_id = devup.get("request_id")
    log.info(
        "chat.ok correlation_id=%s request_id=%s attempts=%d elapsed_s=%.1f",
        correlation_id, request_id, attempts, elapsed,
    )
    balance = devup.get("balance_dzd")
    if low_balance_threshold is not None and isinstance(balance, (int, float)) and balance < low_balance_threshold:
        alert("low_balance", request_id)


def call_with_policy(
    client: OpenAI,
    request: Dict[str, Any],
    *,
    alert: Callable[[str, Optional[str]], None],
    fallback: Optional[Callable[[Dict[str, Any], PolicyError], Optional[Dict[str, Any]]]] = None,
    sleep: Callable[[float], None] = time.sleep,
    now: Callable[[], float] = time.monotonic,
    rand: Callable[[], float] = random.random,
    max_attempts: int = 5,
    max_total_wait_seconds: float = 120.0,
    correlation_id: Optional[str] = None,
    low_balance_threshold: Optional[float] = None,
    account_key: bool = False,  # True only when the client holds an account key: see is_account_key()
) -> Any:
    """Sends one chat completion and applies the action class of every error it gets."""
    started = now()
    waited = 0.0
    capacity_retries = 0
    attempt = 0
    while True:
        attempt += 1
        try:
            completion = client.chat.completions.create(**request)
        except (openai.APIStatusError, openai.APIConnectionError) as exc:
            error = to_policy_error(exc)
        else:
            check_success(
                completion,
                alert=alert,
                correlation_id=correlation_id,
                low_balance_threshold=low_balance_threshold,
                attempts=attempt,
                elapsed=now() - started,
            )
            return completion

        action = error.action
        if error.code in RETRY_THEN_FALLBACK and capacity_retries >= CAPACITY_RETRIES:
            action = FALLBACK
            error.action = FALLBACK  # a raised error reports the action decided here
        if error.code == "service_unavailable" and not account_key:
            # With a Scoped JWT, this code can ask you to contact support first: never send it again automatically.
            action = CONTACT_SUPPORT
            error.action = CONTACT_SUPPORT
        log.warning(
            "chat.error correlation_id=%s request_id=%s status=%s code=%s action=%s attempt=%d",
            correlation_id, error.request_id, error.status, error.code, action, attempt,
        )

        if action == FALLBACK:
            replacement = fallback(request, error) if fallback is not None else None
            if replacement is None or attempt >= max_attempts:
                raise error
            request = replacement
            capacity_retries = 0
            continue
        if action == ADD_FUNDS:
            alert("add_funds", error.request_id)
            raise error
        if action == CONTACT_SUPPORT:
            log.error(
                "chat.contact_support correlation_id=%s request_id=%s: "
                "contact support with the x-request-id before sending the request again",
                correlation_id, error.request_id,
            )
            raise error
        if action == DO_NOT_REPLAY:
            log.error(
                "chat.outcome_pending correlation_id=%s request_id=%s: do not send it again",
                correlation_id, error.request_id,
            )
            raise error
        if action not in (RETRY_AFTER, RETRY_BACKOFF) or attempt >= max_attempts:
            raise error

        delay = retry_delay_seconds(error.headers) if action == RETRY_AFTER else backoff_seconds(attempt)
        delay = min(delay * (1 + 0.2 * rand()), MAX_WAIT_SECONDS)
        if waited + delay > max_total_wait_seconds:
            raise error
        if error.code == "service_unavailable":
            log.warning(
                "chat.service_unavailable correlation_id=%s request_id=%s message=%s",
                correlation_id, error.request_id, error.message,
            )
        if error.code in RETRY_THEN_FALLBACK:
            capacity_retries += 1
        sleep(delay)
        waited += delay


def make_fallback(
    fallback_model: Optional[str],
) -> Callable[[Dict[str, Any], PolicyError], Optional[Dict[str, Any]]]:
    """A fallback hook: drop service_tier first, else switch once to fallback_model."""

    def fallback(request: Dict[str, Any], error: PolicyError) -> Optional[Dict[str, Any]]:
        drops_tier = error.code == "flex_capacity_unavailable" or error.code in RETRY_THEN_FALLBACK
        if drops_tier and "service_tier" in request:
            return {key: value for key, value in request.items() if key != "service_tier"}
        if fallback_model and request.get("model") != fallback_model:
            return {**request, "model": fallback_model}
        return None

    return fallback


def send_alert(event: str, request_id: Optional[str]) -> None:
    """Replace with your paging or chat alert."""
    log.warning("alert event=%s request_id=%s", event, request_id)


def main() -> None:
    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
    api_key = os.environ.get("DEVUP_API_KEY")
    if not api_key:
        print("Set DEVUP_API_KEY.", file=sys.stderr)
        sys.exit(1)
    model = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("DEVUP_MODEL")
    if not model:
        print("Set DEVUP_MODEL or pass a model ID as the first argument.", file=sys.stderr)
        sys.exit(2)
    client = OpenAI(
        api_key=api_key,
        base_url="https://api.devupai.com/v1",
        max_retries=0,
        timeout=300,
    )
    threshold = os.environ.get("LOW_BALANCE_THRESHOLD_DZD")
    request = {
        "model": model,
        "messages": [{"role": "user", "content": "Say hello in one short sentence."}],
    }
    try:
        completion = call_with_policy(
            client,
            request,
            alert=send_alert,
            fallback=make_fallback(os.environ.get("DEVUP_FALLBACK_MODEL")),
            correlation_id=str(uuid.uuid4()),
            low_balance_threshold=float(threshold) if threshold else None,
            account_key=is_account_key(api_key),
        )
    except PolicyError as error:
        print(
            f"{error.action}: {error.code} (HTTP {error.status}), request id {error.request_id}: {error.message}",
            file=sys.stderr,
        )
        sys.exit(1)
    print(completion.choices[0].message.content)


if __name__ == "__main__":
    main()
python policy_client.py

The program prints the reply. When the policy stops, it prints the action class, the code, the HTTP status and the request id of the last error, and exits with status 1. Without a model ID, the Python and the Node.js programs both print Set DEVUP_MODEL or pass a model ID as the first argument. and exit with status 2.

How it works

1Turn off the SDK's retries

    api_key = os.environ.get("DEVUP_API_KEY")
    if not api_key:
        print("Set DEVUP_API_KEY.", file=sys.stderr)
        sys.exit(1)
    model = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("DEVUP_MODEL")
    if not model:
        print("Set DEVUP_MODEL or pass a model ID as the first argument.", file=sys.stderr)
        sys.exit(2)
    client = OpenAI(
        api_key=api_key,
        base_url="https://api.devupai.com/v1",
        max_retries=0,
        timeout=300,
    )

The SDK's own retries are turned off so this code decides when to retry and when to fall back, and so a request whose outcome is not known yet is never sent again automatically. The timeout is 300 seconds per call, long enough for a long reply. The Node.js client uses the SDK's default base URL, https://api.devupai.com/v1, and reads no environment variable itself, so the program passes the key explicitly. Without DEVUP_API_KEY, the program prints Set DEVUP_API_KEY. and exits with status 1 before it creates the client. Both programs also check the model ID before they create the client.

2Map every code to one action class

def classify(status: Optional[int], code: Optional[str]) -> str:
    """The action class of an error: by its code, else by its HTTP status."""
    if code in CODE_CLASS:
        return CODE_CLASS[code]
    if status == 429:
        return RETRY_AFTER
    if status is None or status >= 500:
        return RETRY_BACKOFF
    return FIX_REQUEST

CODE_CLASS lists every code Chat Completions returns, in the table below. The code decides, not the HTTP status: a 429 can mean wait (rate_limit_exceeded) or change the request (flex_capacity_unavailable). A code that is not in the map is classified by its status, so the client keeps working when a code is added: 429 waits, 5xx backs off, and any other 4xx raises. Connection errors and timeouts back off. A request that timed out may already have been processed, so a retry can run it again: acceptable for a chat call, not for work with side effects.

Every error body has the same shape, and every response carries an x-request-id header:

http
HTTP/1.1 429 Too Many Requests
Retry-After: 5
retry-after-ms: 5000
x-request-id: <request_id>

{"error":{"message":"This model is currently at capacity. Retry in a few seconds.","type":"devup_error","code":"model_at_capacity"}}

toPolicyError turns an SDK error into a PolicyError:

def to_policy_error(exc: openai.APIError) -> PolicyError:
    """Turns an SDK error into a PolicyError with its action class."""
    if isinstance(exc, openai.APIStatusError):
        body = exc.body if isinstance(exc.body, dict) else {}
        message = body.get("message") or exc.message
        error = PolicyError(
            code=exc.code,
            status=exc.status_code,
            message=message,
            action=classify(exc.status_code, exc.code),
            request_id=exc.response.headers.get("x-request-id"),
            headers=exc.response.headers,
        )
    else:
        code = "timeout" if isinstance(exc, openai.APITimeoutError) else "connection_error"
        error = PolicyError(code=code, status=None, message=str(exc), action=RETRY_BACKOFF, request_id=None)

In the devupai SDK, a response with an error status is a DevupAPIError or one of its subclasses, and the code reads err.code, err.status, err.message (the message of the error body), err.requestId (the x-request-id header) and err.headers. A 402 insufficient_balance is a plain DevupAPIError, which is why the code decides by err.code and not by the class. When no response arrives, the SDK raises APIConnectionError, or APITimeoutError for a timeout, with status 0. Both are subclasses of DevupAPIError, so the code checks them first. Any other error, such as your own abort, is raised unchanged.

3Read the wait from the headers

def retry_delay_seconds(headers: Any) -> float:
    """Seconds to wait: retry-after-ms, then Retry-After; 1 s when missing or not positive."""
    for name, per_second in (("retry-after-ms", 1000.0), ("retry-after", 1.0)):
        value = headers.get(name) if headers is not None else None
        if value is None:
            continue
        try:
            seconds = float(value) / per_second
        except ValueError:
            continue
        return min(seconds, MAX_WAIT_SECONDS) if seconds > 0 else 1.0
    return 1.0

retry-after-ms is the most precise value, so it is read first; Retry-After is in seconds. A value that is missing, 0 or negative counts as 1 second, and each wait is capped at 30 seconds, so one header can never park a worker. In Node.js, err.headers is a plain object with lower-case header names, so the code reads headers["retry-after-ms"]; in Python, the headers object of the response is read with .get().

4Retry, fall back or stop

        if action == FALLBACK:
            replacement = fallback(request, error) if fallback is not None else None
            if replacement is None or attempt >= max_attempts:
                raise error
            request = replacement
            capacity_retries = 0
            continue
        if action == ADD_FUNDS:
            alert("add_funds", error.request_id)
            raise error
        if action == CONTACT_SUPPORT:
            log.error(
                "chat.contact_support correlation_id=%s request_id=%s: "
                "contact support with the x-request-id before sending the request again",
                correlation_id, error.request_id,
            )
            raise error
        if action == DO_NOT_REPLAY:
            log.error(
                "chat.outcome_pending correlation_id=%s request_id=%s: do not send it again",
                correlation_id, error.request_id,
            )
            raise error
        if action not in (RETRY_AFTER, RETRY_BACKOFF) or attempt >= max_attempts:
            raise error

        delay = retry_delay_seconds(error.headers) if action == RETRY_AFTER else backoff_seconds(attempt)
        delay = min(delay * (1 + 0.2 * rand()), MAX_WAIT_SECONDS)
        if waited + delay > max_total_wait_seconds:
            raise error

Retries stop at max_attempts calls or when the next wait would pass max_total_wait_seconds for the call. A small random jitter spreads the retries of many clients. model_at_capacity and model_unavailable are retried twice after the delay, then handed to the fallback hook. The example hook first sends the request again without service_tier when it has one, then with another model. A fallback counts as an attempt, so the hook cannot loop. CONTACT_SUPPORT logs the x-request-id and stops.

        if error.code == "service_unavailable" and not account_key:
            # With a Scoped JWT, this code can ask you to contact support first: never send it again automatically.
            action = CONTACT_SUPPORT
            error.action = CONTACT_SUPPORT

service_unavailable depends on the key. With a Scoped JWT, its message can ask you to contact support with the request id before you send the request again, and the headers look the same either way, so the client never sends it again automatically: it stops with CONTACT_SUPPORT and logs the x-request-id. With an account key (sk-devup-...), it waits for the delay and sends the request again, and logs the x-request-id and the message before each retry. main() sets accountKey (account_key in Python) from the prefix of the key it holds, and the key itself is never printed. When you call callWithPolicy from your own code, pass it the same way; without it, the client treats the key as a Scoped JWT.

request_outcome_pending is never sent again. The outcome of this request is not known yet; do not send it again. Check the usage export in the dashboard, or contact support with the request id from the x-request-id header.

5Log the request id and watch the balance

    extra = getattr(completion, "model_extra", None) or {}
    devup = extra.get("_devup") or {}
    request_id = devup.get("request_id")
    log.info(
        "chat.ok correlation_id=%s request_id=%s attempts=%d elapsed_s=%.1f",
        correlation_id, request_id, attempts, elapsed,
    )
    balance = devup.get("balance_dzd")
    if low_balance_threshold is not None and isinstance(balance, (int, float)) and balance < low_balance_threshold:
        alert("low_balance", request_id)

A successful response carries a _devup object:

JSON
"_devup": {
  "cost_dzd": <cost_dzd>,
  "balance_dzd": <balance_dzd>,
  "request_id": "<request_id>"
}

request_id is the same value as the response's x-request-id header. cost_dzd is the cost of the request, a number in DZD, and balance_dzd is your balance after it, a number in DZD. The openai package keeps the field in model_extra, its map of fields outside the response schema, and the Python code reads that map with getattr, so an object without it is handled too. The devupai SDK returns the response body as parsed, and types _devup with every field optional, so the Node.js code reads completion._devup ?? {}. When _devup or one of its fields is absent, the check is skipped. The log line carries the request id and your correlation id, never the cost or the balance.

For support, send the request id: _devup.request_id on a success, the x-request-id header on an error. Error bodies do not carry it, so the client reads it from the header; the devupai SDK exposes it as err.requestId.

In production

  • Retry only idempotent work. A chat call is safe to repeat. Your own tool side effects (a payment, an email, a database write triggered by a tool call) are not: run them once, after the reply, with your own idempotency key.
  • One retry budget per user action. When one user action makes several calls, share one max_total_wait_seconds across them instead of giving each call its own.
  • Metrics per action class. Count errors by class and code, and alert on a rise in FIX_REQUEST or FIX_CREDENTIALS: those follow a change on your side, and a retry does not clear them.
  • Keep the request ids in your logs. Store x-request-id or _devup.request_id with your correlation id, so a support request can name the exact call.
  • Route the alerts. Route ADD_FUNDS and low-balance alerts to billing, and NEW_TOKEN errors to whoever issues Scoped JWTs. Neither is fixed by a retry.

Streaming

This recipe sends non-streaming requests. With streaming, an error can also arrive after the first chunk; see Streaming.

Errors this recipe handles

Every code Chat Completions returns, grouped by action class. Each code links to its entry in the error reference.

CodeClassWhat the client does
rate_limit_exceededRETRY_AFTERWaits for retry-after-ms, else Retry-After in seconds (1 s when it is missing, 0 or negative), at most 30 s per wait and 120 s per call, plus a small jitter. Then sends the same request again.
concurrency_limit_exceeded
tpm_limit_exceeded
service_unavailableWith an account key only. With a Scoped JWT: CONTACT_SUPPORT, never sent again automatically.
model_at_capacityAfter 2 retries: FALLBACK.
model_unavailableAfter 2 retries: FALLBACK.
DEVUP_COMPUTE_ERRORRETRY_BACKOFFWaits 1 s, 2 s, 4 s and so on, at most 30 s, plus a small jitter. Then sends the same request again.
unsupported_contentFALLBACKCalls your fallback(request, error) hook and sends the request it returns, for example with another model. Without a hook, or when the hook returns nothing, raises the error.
tools_not_supported
feature_not_supported
response_format_not_supported
flex_capacity_unavailableThe example hook sends the request again without service_tier.
invalid_request_bodyFIX_REQUESTRaises the error. Change the request as the message says before you send it again.
missing_model
missing_tools
invalid_max_tokens
invalid_value
missing_required_parameter
cache_retention_unsupported
use_responses_api
wrong_endpoint
unsupported_parameter
context_length_exceeded
invalid_request_format
empty_message_content
conversation_must_end_with_user
structured_output_mismatchRetrying once can succeed; then simplify the schema.
payload_too_large
invalid_request_error
permission_denied
scoped_budget_unbounded_request
model_configuration_errorHTTP 500. Send max_tokens on every request to this model.
model_not_found
model_not_allowed
invalid_api_keyFIX_CREDENTIALSRaises the error. Check the key and the Authorization: Bearer header.
missing_api_key
token_expiredNEW_TOKENRaises the error. The Scoped JWT expired, was revoked or spent its budget: issue a new one.
token_revoked
budget_exhausted
insufficient_balanceADD_FUNDSCalls alert(), then raises the error. Top up the balance.
account_suspendedCONTACT_SUPPORTLogs the x-request-id and raises the error without sending the request again. Contact support with the request id. With a Scoped JWT, service_unavailable also takes this action.
server_configuration_error
billing_configuration_error
request_outcome_pendingDO_NOT_REPLAYLogs the x-request-id and raises the error without sending the request again. The outcome of this request is not known yet; do not send it again. Check the usage export in the dashboard, or contact support with the request id.

A code that is not in the table is classified by its HTTP status: 429 as RETRY_AFTER, 500 and above as RETRY_BACKOFF, any other 4xx as FIX_REQUEST. Connection errors and timeouts are RETRY_BACKOFF.

Next steps