Códigos de error API
Formas de error, códigos de estado y manejo en el SDK TypeScript de la API System One.
La API System One clasifica cada fallo con un sobre de error estable, un código de estado HTTP y una cabecera de clasificación. Usa esa clasificación para decidir qué hacer en lugar de comparar el texto del mensaje o asumir que todos los cuerpos de error tienen la misma forma. Esta referencia cubre los errores de la API HTTP y el manejo de fallos en el SDK.
Preguntas frecuentes
¿Cómo funciona el manejo de errores de la API System One?
Un sobre de error consistente más códigos de estado HTTP; errores tipados en el SDK de TypeScript; y reintentos con claves de idempotencia cuando corresponde.
El sobre de error de System One
Los errores de la plataforma se identifican con X-System-One-Error-Source: platform. Su cuerpo JSON incluye error.code y, cuando está disponible, el identificador de petición:
{
"error": {
"code": "insufficient_credits",
"message": "This request requires 3 credits. Top up your account to continue.",
"request_id": "example-request-id"
},
"request_id": "example-request-id"
}Los valores son ilustrativos. Para soporte y contabilidad, lee el identificador de petición de la cabecera X-Request-Id. Un error con código provider_* describe un problema al completar la petición al modelo; incluso con HTTP 401 o 403 no significa que tu clave de API ni tu sesión hayan caducado.
Identificar el origen del error
Lee X-System-One-Error-Source junto con X-System-One-Error-Code.
platform: error de System One o sustitución de seguridad. El cuerpo usa el sobre anterior.upstream: el servicio de modelo devolvió un error JSON válido y conserva su estado HTTP original (400–599) y su cuerpo, que puede ser un objeto, un array, una cadena, otro escalar JSON onull. No tiene por qué usar el sobre de System One.
Para errores upstream, la clasificación estable se deriva de la cabecera: provider_busy para HTTP 429 o 529, provider_rejected_request para 400 o 422 y provider_unavailable en cualquier otro caso. Un upstream con 401 o 403 conserva ese estado y no indica que la sesión de System One haya caducado.
Retry-After puede contener segundos o una fecha HTTP y se conserva cuando está disponible de forma segura. Muestra un mensaje localizado basado en la clasificación estable en lugar de mostrar el texto de message o detail: el cuerpo puede reflejar contenido sensible de la petición.
Códigos de error de la plataforma
Estos son los códigos estables de la plataforma:
| Código | HTTP | Qué significa |
|---|---|---|
invalid_api_key | 401 | La clave Bearer falta, es inválida o ha sido revocada. |
unauthorized | 401 | El punto de acceso exige una cuenta o sesión autenticada. |
account_disabled | 403 | La cuenta de la plataforma está deshabilitada. |
invalid_json | 400 | El cuerpo no es JSON válido en UTF-8. |
invalid_request | 422 | Hay campos inválidos o se superan los límites del modelo seleccionado. |
invalid_idempotency_key | 422 | El valor de Idempotency-Key no cumple el formato permitido. |
unsupported_media_type | 415 | Content-Type debe ser application/json. |
unsupported_model | 422 | El identificador de modelo no existe en el catálogo actual. |
request_too_large | 413 | El cuerpo supera el límite de bytes UTF-8 del modelo o del punto de acceso. |
insufficient_credits | 402 | La cuenta no puede reservar los créditos de esta petición. No es un desafío x402. |
rate_limit_exceeded | 429 | Se agotó la cuota de la plataforma; espera a Retry-After. |
idempotency_conflict | 409 | La clave de idempotencia se usó con otra petición. |
request_in_progress | 409 | La operación sigue en curso; espera a Retry-After. |
idempotency_failed | 409 | La operación original falló y sus créditos fueron devueltos. |
idempotency_expired | 410 | El registro de idempotencia ya no tiene datos de reenvío. |
request_expired | 409 | La reserva de la petición caducó antes de completarse. |
provider_not_configured | 503 | El proveedor del modelo no está configurado. |
provider_configuration_error | 503 | La configuración del proveedor necesita atención. |
model_listing_not_supported | 501 | El listado de modelos no está disponible en esta conexión. |
provider_busy | 429 / 529 | El servicio de modelo está ocupado. |
provider_rejected_request | 400 / 422 | El proveedor rechazó la petición. |
provider_unavailable | 502 u otros 4xx / 5xx | No se pudo completar la petición al modelo. |
invalid_provider_response | 502 | El proveedor devolvió una respuesta inválida, no JSON, demasiado grande o una redirección. |
provider_timeout | 504 | El proveedor superó el plazo compartido de 20 segundos para cabeceras y cuerpo. |
request_cancelled | 499 | El cliente canceló la petición. |
request_reconciliation_pending | 503 | El cobro de la petición aún no está liquidado. |
model_catalog_unavailable | 503 | No se pudo cargar el catálogo de modelos actual. |
internal_error | 500 | Error inesperado de la plataforma. |
not_found | 404 | La ruta no existe en el origen documentado. |
method_not_allowed | 405 | El método HTTP no es el documentado para ese punto de acceso. |
Los fallos de autenticación y de validación inicial ocurren antes de reservar una decisión y no consumen créditos de decisión. Un rechazo de admisión, como unsupported_model, no reserva créditos.
Códigos de estado HTTP
| Estado | Significado |
|---|---|
| 400 | JSON ausente, mal formado, no válido en UTF-8 o ambiguo (invalid_json). |
| 401 | Clave Bearer de la plataforma ausente, mal formada, inválida o revocada. |
| 402 | La cuenta no puede reservar los créditos de la petición (insufficient_credits); no es un desafío x402. |
| 403 | La cuenta de la plataforma está deshabilitada. |
| 409 | Conflicto de idempotencia, petición en curso, petición fallida o reserva caducada. |
| 410 | El registro de idempotencia conservado no tiene datos de reenvío (idempotency_expired). |
| 413 | La petición supera el límite de bytes UTF-8 (request_too_large). |
| 415 | Content-Type debe ser application/json (unsupported_media_type). |
| 422 | Campos inválidos, límites del modelo, unsupported_model, extensiones no admitidas o Idempotency-Key inválida; el rechazo de admisión no reserva créditos. |
| 429 | Cuota de la plataforma agotada o proveedor ocupado, con X-RateLimit-Remaining: 0 y Retry-After. |
| 499 | El cliente canceló la petición (request_cancelled). |
| 500 | Error inesperado de la plataforma (internal_error). |
| 501 | El listado de modelos no está disponible (model_listing_not_supported). |
| 502 | Fallo de transporte con el proveedor o respuesta inválida, sobredimensionada, no JSON, con redirección o con credenciales (invalid_provider_response). |
| 503 | Proveedor no configurado o request_reconciliation_pending; en este caso se omite X-System-One-Credits. |
| 504 | El proveedor superó el plazo compartido de 20 segundos para cabeceras y cuerpo. |
Comprobar los cobros antes de reintentar
Una evaluación fallida devuelve los créditos cobrados por ese intento. La cabecera X-System-One-Credits: 0 confirma que no queda ningún cargo retenido. Si la conciliación inmediata no puede completarse, el servicio devuelve request_reconciliation_pending y omite esa cabecera: la ausencia de la cabecera de cargo no significa cero. Consulta créditos y facturación y los registros de uso de tu consola.
Un timeout o una conexión perdida en tu propia herramienta no prueba que la operación haya fallado. Recupérala con la misma clave de operación y el mismo cuerpo. Después de un resultado confirmado de fallo con devolución, un intento nuevo necesita una clave nueva.
Manejo de errores en el SDK de TypeScript
El SDK @system-one-ai/core@0.8.0 exporta APIError con statusCode, requestId y retryAfterMs, pero no expone el cuerpo de error completo del servidor ni las cabeceras de clasificación. Usa Fetch cuando una integración deba distinguir los distintos códigos 409. El SDK oficial mantenido por separado @typesafe-ai/sdk@0.6.0 tiene sus propias clases de error: no asumas que ambos clientes exponen la misma forma ni registres ningún objeto de error completo.
Las políticas de reintento del cliente son independientes del servicio, que no reintenta automáticamente la inferencia del modelo. Los errores de extracción de Clairic usan los mismos campos de APIError.
Para errores o cobros sin resolver, escribe a support@system-one.dev con el identificador de petición, la hora, el estado y el código de error. No envíes la clave de API ni contenido sensible.
Para seguir: referencia de la API, claves de idempotencia, versionado de la API, SDK y facturación y créditos.