Errors and limits

How Sonoe reports problems, what limits apply to your requests, and how tokens are counted.

Error format

Errors on /v1 are JSON with both an error object and a detail:

{
  "detail": "Invalid or revoked API key",
  "error": { "type": "llave_invalida", "message": "Invalid or revoked API key" }
}

error.type is a stable identifier you can switch on; error.message and detail are for people. For invalid fields (422), detail is a list that says where the problem is:

{
  "detail": [
    { "loc": ["body", "questions", "tone", "criteria"], "msg": "A Choice needs between 2 and 255 options.", "type": "value_error" }
  ],
  "error": { "type": "invalid_request_error", "message": "questions.tone.criteria: A Choice needs between 2 and 255 options." }
}

Messages are in English unless you send Accept-Language: es, pt and fr are also available. error.type doesn't change with the language.

Status codes

Status	`error.type`	Meaning	Retry?
`400`	`json_invalido`, `cuerpo_comprimido`	The body isn't valid UTF-8 JSON, or a compressed body doesn't decompress.	No
`401`	`llave_invalida`	The key is missing, wrong, revoked, or its account is disabled.	No
`404`	`modelo_desconocido`	Unknown `model`. Use `sonoe-latest`.	No
`413`	`muy_grande`	The body is over 64 KiB (after decompression).	No
`415`	`codificacion`	`Content-Encoding` other than `zstd`, `gzip` or none.	No
`422`	`invalid_request_error`, `sin_imagenes`	A missing or invalid field, or images / Box questions.	No
`429`	`por_minuto`	Too many requests this minute.	Yes, after `Retry-After`
`429`	`limite_diario`	Your daily token limit is reached.	After midnight UTC
`429`	`cuota_agotada`	Your monthly quota is used up.	On the 1st (UTC)
`429`	`limite_llave`	This key's monthly limit is reached.	On the 1st, or raise it
`429`	`limite_compartido`	The tokens someone shares with you this month are used up.	On the 1st
`503`	`sin_modelo`	The model isn't available on the server right now.	Yes, after a few seconds

Every 429 carries a Retry-After header with the seconds to wait: 10 for the per-minute limit, and the time until the limit resets for the others. The TypeSafe SDKs follow it on their own.

Rate limits

Per minute: 600 requests per minute per key by default. Some accounts have their own limit.
Per day: optional, in tokens. You can set it in the console (Settings › General › Token controller).
Per month: your account's quota, in tokens. It resets on the 1st of each month at 00:00 UTC.
Per key: optional monthly limit for a single key, set when you create it or later in API keys.

Limits are checked before each request, so the request that crosses a limit still completes; the next one gets 429.

Tokens and quotas

You're charged for the tokens Sonoe reads; it writes nothing, so there are no output tokens.

For each question, Sonoe reads the state and the question together with each option, so:

A Noul reads them twice (yes and no).
A Choice reads them once per option.
A Score reads them once per level.

Each read is capped at 256 tokens. A request's total is in usage.input_tokens (/v1/systemone) or usage.tokens (/v1/decide). To spend less: keep the state to what the questions need, keep option lists short, and don't repeat long context inside instructions.

Account	Monthly quota
Trial (new accounts)	5,000 tokens
Authorized team	Set by Sonoe's administrators

Usage, by day, by key and by request, is in the console at sonoeai.com, and you can turn on an alert when you reach a percentage of your quota.

Other limits


Body	64 KiB after decompression
Questions per request	64
Choice options	2 to 255 (`/v1/decide`: 2 to 256)
Score / scale levels	2 to 10
Tokens read per option	256
Active keys per account	25