Errores

El envoltorio del error

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

Este es el mismo envoltorio que usa la propia API de OpenAI, así que el manejo de errores escrito contra un cliente compatible con OpenAI existente debería seguir funcionando sin cambios: revise primero el código de estado HTTP, y lea error.message para un mensaje que valga la pena mostrar a un desarrollador o registrar en logs. error.type es una categoría estable y verificable por máquina, útil para lógica de bifurcación (reintentar o no, pedir una nueva clave de API o esperar y volver a intentar) sin tener que analizar el mensaje de texto libre.

Códigos de estado y tipos

Estado	Tipo	Significado
400	invalid_request_error	La propia solicitud está mal formada: un model no reconocido, un array messages ausente o vacío, un mensaje con un rol no admitido, o una definición de tools mal formada. Corrija la solicitud; reintentar sin cambiar nada fallará de la misma manera todas las veces.
401	authentication_error	Falta el encabezado Authorization, está mal formado, o la clave es inválida, expiró, o fue revocada. Vea Autenticación.
429	rate_limit_error	Demasiadas solicitudes en una ventana corta con esta clave. Vea Límites de tasa para conocer el límite y cómo esperar correctamente antes de reintentar.
500	api_error	Un error inesperado del lado del servidor que no tiene relación con su solicitud. Poco frecuente; seguro de reintentar, idealmente con una breve espera.
503	api_error	El servicio no puede completar la solicitud temporalmente, típicamente un problema transitorio en la propia infraestructura de generación de tAI y no algo incorrecto en su solicitud. Seguro de reintentar.

Algunos ejemplos

Un modelo desconocido:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

Una clave inválida o expirada:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

Un problema transitorio del servicio:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

Errores a mitad de un stream

Una vez que una respuesta en streaming ha comenzado (la conexión está abierta y ya han empezado a llegar chunks), un error ya no puede reportarse como un cuerpo JSON de error normal con un estado fuera de 2xx, ya que el estado HTTP y los encabezados ya se enviaron como 200 al inicio del stream. En cambio, un fallo que ocurre a mitad de un stream se muestra como un chunk de contenido visible (típicamente un breve aviso entre corchetes) seguido de un chunk de finalización normal y [DONE], en lugar de que la conexión simplemente se caiga. Vea Streaming para la forma exacta y por qué el stream tiene garantizado terminar de forma limpia en cualquier caso.

Qué vale la pena reintentar

Como regla general: los errores 400 y 401 describen algo incorrecto en la solicitud o en la propia clave, y reintentar de forma idéntica fallará de forma idéntica todas las veces, así que primero hay que corregir el problema de fondo. 429, 500 y 503 son todos seguros de reintentar, idealmente con una breve espera y un límite en el número total de intentos, en lugar de reintentar en un bucle apretado; vea Límites de tasa específicamente para saber cómo esperar correctamente ante un 429.