Errors

The error envelope

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "message": "The account's remaining credit cannot cover this request.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Branch on code, not on message: messages can be reworded, codes do not change. type follows the HTTP status:

During a stream the status is already 200, so errors arrive as an event, data: {"error": {…}}, followed by data: [DONE]. Check each event for an error key.

Request ids

Every response from POST /v1/chat/completions, POST /v1/messages and POST /v1/messages/count_tokens, successful or not, carries an X-Request-Id header such as req_3f9a… (req_ and 32 hex digits). It is random and identifies nothing but that response. Quote it when you report a problem.

When one of these requests answers 400, Sevren keeps it for up to 7 days so the error can be debugged: the request body (up to 64 KiB), the error answer and, if the model refused the request, the model's answer, under that request id. No IP address, API key or account is stored with it. Requests that do not get a 400, and requests the child-safety screen refuses, are never stored. See Privacy.

Model API

POST /v1/chat/completions and GET /v1/models on api.example.com. POST /v1/messages and POST /v1/messages/count_tokens answer the same statuses in Anthropic's shape, {"type": "error", "error": {"type", "message"}}, without the code; see Anthropic API.

Account API

Routes under /account on api.example.com.

Wallet routes

Routes under /auth on auth.example.com.

Rate limits and Retry-After

Limits are counted per model, per account or for the whole service. The one exception is free questions without an account, counted under a keyed pseudonym of the IP address that changes every UTC day (see Privacy):

Retry-After is a number of seconds. The model API sets it to the time left in the current window, the account API to 60, and maintenance responses to 60. The wallet routes do not send it; their budgets reset every minute.

Retrying

• Retry 429, 502, 503 and 504: wait for Retry-After when it is present, otherwise back off exponentially.
• Do not retry other 4xx errors unchanged; fix the request, sign in again or add credit first.
• A retried request is a new request and is charged again if it runs.

import time, requests

def post_with_retry(url, **kwargs):
    for attempt in range(5):
        response = requests.post(url, timeout=320, **kwargs)
        if response.status_code not in (429, 502, 503, 504):
            return response
        wait = response.headers.get("Retry-After")
        time.sleep(int(wait) if wait and wait.isdigit() else 2 ** attempt)
    return response