Errores y límites

Cómo avisa Sonoe de los problemas, qué límites aplican a tus solicitudes y cómo se cuentan los tokens.

Formato de los errores

Los errores en /v1 son JSON con un objeto error y un detail:

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

error.type es un identificador estable para tu código; error.message y detail son para personas. Con campos inválidos (422), detail es una lista que dice dónde está el problema:

{
  "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." }
}

Los mensajes vienen en inglés salvo que mandes Accept-Language: también hay es, pt y fr. Con Accept-Language: es, por ejemplo:

{
  "detail": "No existe el modelo «gpt-5». Usa sonoe-latest (o jev-latest).",
  "error": { "type": "modelo_desconocido", "message": "No existe el modelo «gpt-5». Usa sonoe-latest (o jev-latest)." }
}

error.type no cambia con el idioma.

Códigos de estado

Estado	`error.type`	Qué pasa	¿Reintentar?
`400`	`json_invalido`, `cuerpo_comprimido`	El cuerpo no es JSON UTF-8 válido, o un cuerpo comprimido no se puede descomprimir.	No
`401`	`llave_invalida`	La key falta, está mal, fue revocada o su cuenta está desactivada.	No
`404`	`modelo_desconocido`	`model` desconocido. Usa `sonoe-latest`.	No
`413`	`muy_grande`	El cuerpo pasa de 64 KiB (después de descomprimir).	No
`415`	`codificacion`	Un `Content-Encoding` que no es `zstd`, `gzip` ni ninguno.	No
`422`	`invalid_request_error`, `sin_imagenes`	Un campo ausente o inválido, o imágenes / preguntas Box.	No
`429`	`por_minuto`	Demasiadas solicitudes este minuto.	Sí, tras `Retry-After`
`429`	`limite_diario`	Llegaste a tu límite diario de tokens.	Después de la medianoche UTC
`429`	`cuota_agotada`	Se acabó tu cuota del mes.	El día 1 (UTC)
`429`	`limite_llave`	Esta key llegó a su límite del mes.	El día 1, o súbelo
`429`	`limite_compartido`	Se acabaron los tokens que alguien comparte contigo este mes.	El día 1
`503`	`sin_modelo`	El modelo no está disponible en el servidor ahora mismo.	Sí, en unos segundos

Cada 429 trae un encabezado Retry-After con los segundos que esperar: 10 para el límite por minuto y, para los demás, el tiempo que falta para que el límite se renueve. Los SDK de TypeSafe lo siguen solos.

Límites de uso

Por minuto: 600 solicitudes por minuto por key de forma predeterminada. Algunas cuentas tienen su propio límite.
Por día: opcional, en tokens. Lo defines en la consola (Ajustes › General › Controlador de tokens).
Por mes: la cuota de tu cuenta, en tokens. Se renueva el día 1 de cada mes a las 00:00 UTC.
Por key: un límite mensual opcional para una sola key, que se fija al crearla o después en API keys.

Los límites se revisan antes de cada solicitud, así que la solicitud que cruza un límite sí se completa; la siguiente recibe 429.

Tokens y cuotas

Se cobra por los tokens que Sonoe lee; no escribe nada, así que no hay tokens de salida.

En cada pregunta, Sonoe lee el estado y la pregunta junto con cada opción, así que:

Un Noul los lee dos veces (sí y no).
Un Choice los lee una vez por opción.
Un Score los lee una vez por nivel.

Cada lectura tiene un tope de 256 tokens. El total de una solicitud está en usage.input_tokens (/v1/systemone) o usage.tokens (/v1/decide). Para gastar menos: deja en el estado solo lo que las preguntas necesitan, mantén cortas las listas de opciones y no repitas contexto largo dentro de instructions.

Cuenta	Cuota mensual
Prueba (cuentas nuevas)	5,000 tokens
Equipo autorizado	La fijan los administradores de Sonoe

El uso, por día, por key y por solicitud, está en la consola en sonoeai.com, y puedes activar un aviso cuando llegues a un porcentaje de tu cuota.

Otros límites


Cuerpo	64 KiB después de descomprimir
Preguntas por solicitud	64
Opciones de Choice	De 2 a 255 (`/v1/decide`: de 2 a 256)
Niveles de Score / scale	De 2 a 10
Tokens leídos por opción	256
Keys activas por cuenta	25