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
| Status | code | Anthropic-format type | Means | What to do |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_request_error | The 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. |
| 400 | unsupported_tool_type | invalid_request_error | A built-in tool type this model can’t use. | Use function tools. |
| 400 | content_blocked, content_blocked_support, history_blocked | invalid_request_error | Our safety filter stopped the request. | See Blocked messages. |
| 401 | invalid_api_key | authentication_error | No key, or one that’s malformed, revoked or unknown. | Check the key. See Authentication. |
| 403 | account_restricted | permission_error | This account can’t use models right now. | See below. |
| 404 | model_not_found | not_found_error | No model with that id can be called right now. | Check the id against GET /v1/models. |
| 404 | not_found | not_found_error | No such endpoint. | Check the path and base URL. |
| 405 | null | invalid_request_error | The endpoint exists, but not with that method. | Use POST, or GET for the model list. |
| 409 | idempotency_conflict | invalid_request_error | That Idempotency-Key is in use or already done. | See Idempotency keys. |
| 413 | invalid_request_error | invalid_request_error | The request is too large: over 8 MiB, or more than the model accepts. | Send less. |
| 429 | rate_limit_exceeded, with type requests or tokens | rate_limit_error | Your key reached its limit for this minute. | Wait for retry-after. See Rate limits and timeouts. |
| 429 | insufficient_quota | invalid_request_error | Your balance can’t cover the request. | Add credit. See below. |
| 429 | rate_limit_exceeded, with type server_error | rate_limit_error | The model is busy. | Retry after retry-after, which is 2 seconds. |
| 429 | abuse_pattern | invalid_request_error | Sending is paused after repeated blocked messages. | See Blocked messages. |
| 502 | server_error | api_error | The model couldn’t complete the request, or didn’t answer in time. | Retry with backoff. |
| 503 | server_error | api_error | The model or the service is unavailable for a moment. | Retry with backoff. |
| 503 | maintenance | service_unavailable | Kalsenti 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.
| code | Means |
|---|---|
content_blocked | Something in the newest part of the conversation can’t be sent. |
history_blocked | Something in an earlier message can’t be sent. Start the conversation again without it. |
content_blocked_support | The 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_pattern | After 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.completedorresponse.incompleteafter 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:
429rate limits and a busy model: wait for theretry-afterheader, in seconds.502and503: 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 a400. - 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
409withidempotency_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
idin the response body, such aschatcmpl_…ormsg_….
Log the request ID with every error you record. It’s the quickest way for us to find what happened.
curl -i https://gateway.kalsenti.ai/v1/models -H "Authorization: Bearer $KALSENTI_API_KEY"