Errores y reintentos

Idioma de los mensajes de error

Los textos de error pensados para personas pueden llegar en el idioma que elijas. Afecta a tres campos: msg en la respuesta, errorMessage de una tarea fallida (tanto en recordInfo como en las entregas de webhook) y error.message en los objetos de error de las API compatibles, ya sigan el formato de OpenAI, de Anthropic o de Google Gemini. El idioma predeterminado es el inglés. Códigos de idioma admitidos: en, zh-Hant, ja, ko, de, fr, es, pt-BR, ru.

Solo cambia el texto legible. Los valores de code y errorCode, los de type y code en la capa compatible con OpenAI, los de code y status en la capa compatible con Gemini y todos los nombres de campo son iguales en cualquier idioma. Bifurca siempre por códigos, nunca analices el texto, y guarda code y request_id en tus registros y alertas. La cabecera de respuesta Content-Language indica el idioma que se usó realmente. Por ejemplo, para el mismo 40201 (saldo insuficiente), msg vale “Insufficient balance” de forma predeterminada; con Accept-Language: ja, msg llega en japonés y code sigue siendo 40201.

El idioma se decide en este orden:

• Cabecera Accept-Language: se aplica solo a esa solicitud. Sigue la ponderación estándar de HTTP: se elige el idioma reconocido con el valor q más alto. Las variantes regionales se asignan a su idioma: de-DE pasa a de, pt-PT a pt-BR, y zh-TW, zh-HK y zh-Hant a zh-Hant. El chino solo se ofrece en caracteres tradicionales, así que zh-CN y zh-Hans no coinciden con ningún idioma y se pasa al siguiente candidato. * se interpreta como sin preferencia.
• Ajuste de la cuenta: en la consola, “Ajustes → Idioma de los errores de la API”. Se aplica a toda solicitud enviada con una clave API de esta cuenta que no incluya una cabecera Accept-Language reconocible. La mayoría de los SDK de servidor y curl no envían esta cabecera de forma predeterminada, así que en la práctica es la opción más habitual. Las entregas de webhook no tienen cabecera de solicitud y siempre siguen el ajuste de la cuenta.
• Si no hay ninguno de los dos, se usa el inglés.

# Default: no Accept-Language, no account setting
HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

# The same request with one extra header
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

Errores que no deben reintentarse

400, 401, 403, 404, 40201, 40202 y 40301–40303 no cambiarán hasta corregir la entrada, credenciales, permisos, saldo o límites. Un 413 indica que el cuerpo es demasiado grande: no lo reintentes igual, redúcelo o usa la carga de medios.

Errores reintentables

Para 429 respeta Retry-After. En HTTP 500/503 y códigos de negocio 500/50301 usa espera exponencial con jitter. Un 409 depende de la operación: reintenta solo media pending o el infrecuente conflicto concurrente de createTask con el mismo Idempotency-Key y el mismo payload. Un conflicto de clave con otro payload no se reintenta.

En un fallo de red de createTask reutiliza el mismo Idempotency-Key. La misma clave con otro payload devuelve 409.

Facturación

Una solicitud rechazada antes de crear la tarea no se factura. Después, failed, expired y los registros canceled históricos liberan toda la reserva. Una tarea nueva aceptada no se puede cancelar; solo succeeded se liquida según el uso real.