ITS INCOM AI ITS INCOM AI docs

API reference

Errors

The shapes errors come in, the statuses the API really returns, and which ones are worth retrying.

Last updated: 2026-10-03

On /v1, most errors have the OpenAI shape:

json
{
  "error": {
    "message": "unknown tier: turbo",
    "type": "invalid_request_error"
  }
}

message and type are always there. Depending on the error you also get code, param (the field at fault) and request_id. The app API has its own codes, listed in Authentication.

Many messages are in Italian today. Write your code against the HTTP status, type and code, not against the text.

Three errors with a different shape

These three are produced by the framework the API is built on, and have a message at the top level instead of the error object.

Validation of chat completions, 422: a required field missing, or a value out of range (max_tokens above 8192, an unknown role). The keys of errors are the fields at fault:

json
{
  "message": "…",
  "errors": {
    "messages": ["…"]
  }
}

Rate limit per address, 429:

json
{ "message": "Too Many Attempts." }

Unexpected error on our side, 500:

json
{ "message": "Server Error" }

Status codes

HTTP type / code When What to do
400 invalid_request_error A parameter we do not recognise or refuse, named in param (the list); an image we cannot accept; an unknown X-Siati-Tier. On embeddings, rerank, audio and responses, also a missing or invalid field Fix the request
401 invalid_request_error, code invalid_api_key Key missing, malformed, unknown, revoked or expired, or account disabled See Authentication
404 invalid_request_error, code unknown_endpoint The path does not exist, or exists for another method: GET /v1/chat/completions gets 404, not 405 Check path and method
404 type model_not_found The model is not in the catalogue GET /v1/models lists the valid ones
422 none, see above Chat completions: a required field missing or out of range Read errors
429 type rate_limit_exceeded, or Too Many Attempts. Limit per key, or limit per address Wait Retry-After seconds. See Rate limits
500 usually none, see above A bug on our side Retry once; if it repeats, write to us
501 code stream_not_implemented "stream": true on /v1/responses Stream with chat completions
501 type not_implemented /v1/rerank where it is turned off —
502 type bad_gateway The machines that could serve the request did not answer Retry after a short wait
503 type zone_unavailable No machine for the model is available in your key's zones. The message names the zones: we do not move the request elsewhere Retry later. If it persists, your key may have no zone where that model runs: write to segreteria@itsincom.it
503 type model_unavailable No machine for the model is available Retry later, or use another model
503 type model_activation_required The model is in the catalogue on request, and is not loaded now Retrying will not help: write to segreteria@itsincom.it

zone_unavailable, model_unavailable and model_activation_required come from text generation (chat completions and responses). When one machine fails, the request has already moved to the next one in your zones: a 502 means none of them answered.

Errors in a stream

Once a stream has started the status is 200, and an error arrives as an event with an error object; the stream then ends without [DONE]. See Streaming.

What is charged

A request refused with a 4xx costs nothing, and neither does a request that ends in 502. When a machine fails and the next one answers, you pay once, for the answer you received.

Retrying

Status Retry?
429 Yes, after Retry-After seconds
502, 503 model_unavailable, 503 zone_unavailable Yes, after a wait that grows at each attempt
500 Once
400, 401, 404, 422, 501, 503 model_activation_required No: the same request fails the same way

A retry is a new request: it counts against your rate limits.

Reporting a problem

Every response carries an X-Request-Id header. Chat completions also carry an identifier in the body: the id of the answer, or request_id inside most errors. The two are not always the same, so send both to segreteria@itsincom.it, with the time of the request. curl -i shows the headers:

bash
curl -i https://api.ai.itsincom.org/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma-4-26b", "messages": [{"role": "user", "content": "Hello"}]}'

Common mistakes

  • curl without Content-Type: application/json. The body is read as a form, and you get 422 saying that model and messages are missing. The OpenAI SDKs set the header for you.
  • A body that is not valid JSON. Same 422: the body is read as empty.
  • The wrong method. GET on an endpoint that takes POST answers 404 unknown_endpoint.
  • Document search with an API key. /v1/rag/… does not exist and answers 404: document search is in the app API, with a user token. See Authentication.
  • A user token on /v1. It answers 401 with invalid api key format: /v1 takes API keys only.