Códigos de error y resolución de problemas

Identifica qué ha fallado

1. Registra el estado HTTP real, método y ruta de la solicitud. El estado HTTP y el código de error de aplicación describen capas distintas; no sustituyas uno por otro.
2. Lee los campos de error según el protocolo utilizado. Las respuestas nativas, OpenAI, Claude y Gemini no comparten siempre la misma estructura.
3. Para solicitudes en streaming, inspecciona también los eventos de error y el estado de finalización. Para tareas asíncronas, inspecciona status. HTTP 200 no garantiza una generación correcta.
4. Usa la tabla siguiente para corregir la solicitud o decidir si reintentar. message es texto explicativo, no una enumeración estable; no bases las bifurcaciones en su redacción.

Enumeración de códigos de error de la plataforma

Esta es la enumeración completa de códigos de error de aplicación de la plataforma. Los nombres son etiquetas de referencia; los valores code de la respuesta son números. «HTTP habitual» es una guía de diagnóstico, no una correspondencia fija para cada endpoint. Usa el estado HTTP y cuerpo reales. Un code reenviado del proveedor puede no pertenecer a esta enumeración.

HTTP 429 por sí solo no distingue de forma fiable límites de frecuencia y de concurrencia. Haz esa distinción solo cuando exista un código numérico explícito. Comprueba los identificadores en la lista de modelos; no reescribas los valores de model por tu cuenta.

Lee los errores según el protocolo

Los ejemplos siguientes muestran estructuras habituales generadas por la plataforma, no un formato único garantizado para cualquier fallo. Los errores de autenticación pueden proceder de distintas capas y las respuestas reenviadas del proveedor pueden conservar su estructura, códigos de cadena o tipos. Identifica la estructura real antes de analizarla. Si no la reconoces, conserva los campos originales y estado HTTP en lugar de forzar una conversión.

API nativas de la plataforma

Normalmente se leen error.code y error.message. requestId puede no existir.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Algunos errores pueden usar code y message de nivel superior. Los clientes deben tolerar esta diferencia y no interpretar la ausencia de un objeto error como prueba de éxito. Las respuestas de validación también pueden carecer de código numérico. Trata un código ausente como desconocido, sin inventarlo.

API compatibles con OpenAI

Los errores habituales generados por la plataforma usan code, message y type de nivel superior; no siempre están encapsulados en error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type es una categoría del protocolo; code es el código numérico de plataforma en esta estructura. api_error por sí solo no determina si conviene reintentar. Los errores reenviados del proveedor o del streaming pueden contener un error anidado; trata la respuesta real del protocolo. Consulta Chat Completions y Responses.

API compatibles con Claude

En la estructura habitual, type de nivel superior es error, la categoría concreta es error.type y la descripción es error.message. Esta estructura no incluye un code numérico de plataforma. No lo inventes.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

La plataforma genera localmente los siguientes tipos de error de Claude. No es una enumeración exhaustiva de los tipos del proveedor.

Consulta Claude Messages.

Errores al estilo Gemini

Si recibes una respuesta al estilo Gemini, lee error.code, error.message y error.status. Aquí, status es una categoría de cadena, no un estado HTTP ni de tarea asíncrona.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Los errores de plataforma con esta estructura usan valores code numéricos de plataforma. La correspondencia local de status se muestra abajo; no enumera todos los estados del proveedor.

503 tiene prioridad y usa UNAVAILABLE, no INTERNAL. Las respuestas del proveedor pueden usar otra semántica para code y status. No apliques la tabla de códigos de plataforma a todos los códigos numéricos de Gemini.

Reintentos prudentes

Respeta una cabecera Retry-After válida cuando exista. No supongas que todos los errores la incluyen. Reintentar automáticamente una generación no idempotente puede ejecutarla de nuevo y generar cargos adicionales. Esta página no promete compatibilidad general con claves de idempotencia; añadir Idempotency-Key por tu cuenta no garantiza la deduplicación.

Si ya tienes un jobId, consulta esa tarea antes de crear otra. Si no tienes jobId y el resultado es incierto, conserva el identificador de solicitud y su marca de tiempo para investigar.

Flujos y tareas asíncronas

Solicitudes SSE

Tras iniciar SSE, el estado HTTP puede seguir siendo 200 mientras un fallo posterior se comunica mediante un evento de error o datos en el flujo. Analiza eventos y datos según el protocolo y comprueba la finalización normal. Ante un error o desconexión inesperada, no trates texto o imágenes parciales como un resultado completo correcto. Los nombres de eventos y datos varían entre endpoints. No compruebes solo un campo fijo error ni uses «se recibió algún texto» como condición de éxito.

Tareas asíncronas

Una respuesta de creación con data.jobId significa que la solicitud fue aceptada, no que la generación terminó. Una respuesta HTTP correcta al consultar una tarea indica que la consulta tuvo éxito. Aún debes inspeccionar data.status:

• PENDING, CONNECT, PROCESSING: sigue consultando como indica la documentación de Jobs.
• COMPLETED: lee outputResult.
• FAILED, CANCELLED: deja de consultar y conserva el ID y la respuesta sin información sensible para investigar.

Los detalles del fallo pueden aparecer en data.outputResult.error. Este campo es opcional y no se garantiza en todas las tareas fallidas. Usa Jobs solo si la respuesta de creación devuelve explícitamente un jobId. No apliques consultas de tareas a endpoints que devuelven resultados directamente por JSON o SSE.

Diagnóstico para usuarios y asistentes de IA

Proporciona la siguiente información sin datos sensibles a soporte o a un asistente de IA. Usa unknown para campos ausentes; usa unknown para el estado HTTP si no se recibió respuesta HTTP. Conserva rutas de campos y tipos originales, por ejemplo error.code: 10000 (number) o error.code: "invalid_api_key" (string). No conviertas automáticamente un code de cadena en un código numérico de plataforma ni inventes campos ausentes a partir de message, estado HTTP o nombres de modelos.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Lee requestId del cuerpo o de la cabecera X-Request-ID cuando exista. Mantén jobId como cadena para evitar pérdida de precisión con números largos. Proporciona solo los parámetros mínimos sin información sensible. Elimina claves de API, tokens, cookies, cabeceras completas de autenticación, información personal, instrucciones privadas y contenido de archivos de entrada. Elimina parámetros de URL y URL de entrada/salida con firmas o credenciales. No pegues registros completos sin revisarlos.

Los asistentes de IA deben distinguir campos observados de posibles causas e identificar la información ausente. La falta de pruebas no demuestra que una solicitud tuviera éxito, no se ejecutara o no generara cargos.