Cookbook Recipe
Error handlingHandle 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.
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
openaipackage, or Node.js 22.12 or later with thedevupaipackage. - An API key (
sk-devup-...) or a Scoped JWT inDEVUP_API_KEY. See Authentication. - A model ID from
GET /v1/modelsinDEVUP_MODEL, or as the first argument of the program. - Optional:
DEVUP_FALLBACK_MODEL, a second model ID for the fallback hook, andLOW_BALANCE_THRESHOLD_DZD, a number in DZD below which a successful call alerts you.
pip install openaiexport 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.pyThe 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_REQUESTCODE_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/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.0retry-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 errorRetries 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_SUPPORTservice_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:
"_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_secondsacross 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-idor_devup.request_idwith 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.
| Code | Class | What the client does |
|---|---|---|
| rate_limit_exceeded | RETRY_AFTER | Waits 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_ERROR | RETRY_BACKOFF | Waits 1 s, 2 s, 4 s and so on, at most 30 s, plus a small jitter. Then sends the same request again. |
| unsupported_content | FALLBACK | Calls 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_body | FIX_REQUEST | Raises 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_key | FIX_CREDENTIALS | Raises the error. Check the key and the Authorization: Bearer header. |
| missing_api_key | ||
| token_expired | NEW_TOKEN | Raises the error. The Scoped JWT expired, was revoked or spent its budget: issue a new one. |
| token_revoked | ||
| budget_exhausted | ||
| insufficient_balance | ADD_FUNDS | Calls alert(), then raises the error. Top up the balance. |
| account_suspended | CONTACT_SUPPORT | Logs 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_pending | DO_NOT_REPLAY | Logs 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.