Guides

Errors

Every error the API returns, what it means and what to do about it, with how to retry safely.

On this page

Error format

Errors come back as JSON, in the format of the endpoint you called. Endpoints in the OpenAI format put a code on every error. Messages and count tokens use the Anthropic format, which has a type instead, and so does the model list when you send anthropic-version.

{
  "error": {
    "message": "Credit balance is too low",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

Messages are short and fixed (except the maintenance message, which our team writes), so you can show them to people, but branch on the status and code rather than the wording. When a field is at fault, paramnames it.

All errors

StatuscodeAnthropic-format typeMeansWhat to do
400invalid_request_errorinvalid_request_errorThe body isn’t valid JSON, a field is missing or invalid, a feature isn’t supported, or a header is wrong. param says which.Fix the request. Don’t retry it unchanged.
400unsupported_tool_typeinvalid_request_errorA built-in tool type this model can’t use.Use function tools.
400content_blocked, content_blocked_support, history_blockedinvalid_request_errorOur safety filter stopped the request.See Blocked messages.
401invalid_api_keyauthentication_errorNo key, or one that’s malformed, revoked or unknown.Check the key. See Authentication.
403account_restrictedpermission_errorThis account can’t use models right now.See below.
404model_not_foundnot_found_errorNo model with that id can be called right now.Check the id against GET /v1/models.
404not_foundnot_found_errorNo such endpoint.Check the path and base URL.
405nullinvalid_request_errorThe endpoint exists, but not with that method.Use POST, or GET for the model list.
409idempotency_conflictinvalid_request_errorThat Idempotency-Key is in use or already done.See Idempotency keys.
413invalid_request_errorinvalid_request_errorThe request is too large: over 8 MiB, or more than the model accepts.Send less.
429rate_limit_exceeded, with type requests or tokensrate_limit_errorYour key reached its limit for this minute.Wait for retry-after. See Rate limits and timeouts.
429insufficient_quotainvalid_request_errorYour balance can’t cover the request.Add credit. See below.
429rate_limit_exceeded, with type server_errorrate_limit_errorThe model is busy.Retry after retry-after, which is 2 seconds.
429abuse_patterninvalid_request_errorSending is paused after repeated blocked messages.See Blocked messages.
502server_errorapi_errorThe model couldn’t complete the request, or didn’t answer in time.Retry with backoff.
503server_errorapi_errorThe model or the service is unavailable for a moment.Retry with backoff.
503maintenanceservice_unavailableKalsenti is paused for maintenance, so no model can be called until it ends.Wait for retry-after, which is 60 seconds, then retry.

A 400 with the message “The request was not accepted. Check the parameters and try again” means the model itself turned the request down, for example because it’s longer than the context window or a value is out of range.

A 503 with maintenance means the whole platform is paused, not one model. The message is written by our team and may say when we expect to be back; retry-after is 60 seconds. Retrying sooner does no harm, but it keeps answering the same way until maintenance ends.

Out of credit

Before a reply starts, enough credit is set aside to cover it at its longest: the input, plus max_tokens of output (16,000 if you didn’t say). If your balance, less what other running requests have set aside, can’t cover that, the request isn’t run, costs nothing, and you get a 429 with the code insufficient_quota.

  • Add credit on the Billing page. Requests work again as soon as it lands.
  • Or lower max_tokens, so less needs setting aside.
  • Don’t retry it in a loop: it fails the same way until your balance changes.

In the Anthropic format this error has the type invalid_request_error, which is how it differs from a rate limit (rate_limit_error) with the same status. A low balance can also email you first: see Low balance.

Account can’t use models

A 403 with account_restricted means your account can’t use models at the moment: for example, Kalsenti isn’t available in your country yet, a payment came from a billing address in a country we don’t serve and is being reviewed, or the account has been closed. Your dashboard says which. Retrying won’t help. If you think it’s wrong, email support@kalsenti.ai.

Blocked messages

Every request, on every model, is checked by an automated safety filter for a small number of serious categories, as our Privacy policy explains. A blocked request never reaches a model, costs nothing and doesn’t appear on the Usage page. The Acceptable use policy says what isn’t allowed.

codeMeans
content_blockedSomething in the newest part of the conversation can’t be sent.
history_blockedSomething in an earlier message can’t be sent. Start the conversation again without it.
content_blocked_supportThe message suggests someone may be at risk of harming themselves. If it came from one of your users, show them where to find support.
abuse_patternAfter several blocked requests in a short time, chat and the API are paused for your account for an hour. It’s a 429; try again later.

If you think the filter got it wrong, email support@kalsenti.ai with the request ID and a person will look at it.

Errors during a stream

Problems found before a stream starts come back as ordinary errors with their status code. Once a stream has started, the status is already 200, so if the model fails part way through, the stream sends one error event and ends:

data: {"error":{"message":"The model could not complete the request. Try again","type":"server_error","param":null,"code":"server_error"}}
  • There’s no [DONE], message_stop, response.completed or response.incomplete after it.
  • The stream isn’t restarted for you, and the text you already received is all there is. It’s charged for what was produced, and shows as failed on the Usage page.
  • A stream that ends with neither its last event nor an error event was cut off on the way, for example by a network drop.

Retrying

Retry these, waiting longer each time:

  • 429 rate limits and a busy model: wait for the retry-after header, in seconds.
  • 502 and 503: wait a second or two, then double it each time, with a little randomness, for a few attempts.

Don’t retry the rest: 400, 401, 403, 404, 413, and 429 with insufficient_quota or abuse_pattern fail the same way until something changes. The OpenAI and Anthropic SDKs retry on their own unless you turn that off: see Retries in the SDKs.

A retry loop

import os, random, time, uuid
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key=os.environ["KALSENTI_API_KEY"],
    base_url="https://gateway.kalsenti.ai/v1",
    max_retries=0,
)

RETRY_STATUSES = {429, 502, 503}
NEVER_RETRY = {"insufficient_quota", "abuse_pattern"}

def create_with_retries(attempts=5, **params):
    key = str(uuid.uuid4())  # the same key on every attempt
    for attempt in range(attempts):
        try:
            return client.chat.completions.create(
                **params, extra_headers={"Idempotency-Key": key}
            )
        except APIStatusError as error:
            last = attempt == attempts - 1
            if last or error.status_code not in RETRY_STATUSES or error.code in NEVER_RETRY:
                raise
            wait = error.response.headers.get("retry-after")
            time.sleep(float(wait) if wait else 2 ** attempt + random.random())

Idempotency keys

A request that timed out on your side may still have run. Send an Idempotency-Key header, the same on every attempt, so a retry can never run and charge twice. It works on chat completions, Responses and Messages.

  • A key is 1 to 128 letters, digits, - or _, such as a UUID. Anything else gets a 400.
  • Keys belong to the API key that sent them, so two of your apps can’t collide.
  • While a request with that key is running, another one gets a 409 with idempotency_conflict.
  • Once it has finished, the key is used up for 24 hours, and a repeat gets the same 409. The first reply can’t be fetched again; its result is on the Usage page.
  • A request that fails before the model answers, such as a 502, doesn’t use up its key, so you can retry with the same one.
  • Once a stream has started, its key is used up even if the stream breaks. Retry a broken stream with a new key.

Request IDs

Every response, successful or not, has an x-request-id header, such as req_6c1f2e8a90b34d7f8e21c5a0b9d34f17. The same value is sent as request-id.

  • Search for it on the Usage page to see what the request did and cost.
  • Include it when you email support@kalsenti.ai.
  • It isn’t the id in the response body, such as chatcmpl_… or msg_….

Log the request ID with every error you record. It’s the quickest way for us to find what happened.

See the headers
curl -i https://gateway.kalsenti.ai/v1/models -H "Authorization: Bearer $KALSENTI_API_KEY"