Errores de la API GPT-6 Astra: 15 problemas comunes y cómo solucionarlos

La forma más rápida de empeorar un incidente de API es reintentar cada error. Un esquema mal formado no se curará con retroceso, y un saldo de crédito agotado no se recuperará porque un trabajador lo intentó diez veces más. Diagnostique los errores por estado HTTP, clase de SDK, error.type y especialmente error.code.

Un manejador de errores seguro

intenta {
  return await client.responses.create({
    model: "gpt-6-astra",
    input
  });
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    // Network, proxy, TLS, DNS or firewall path.
  } else if (error instanceof OpenAI.RateLimitError) {
    // Inspect code and Retry-After before deciding to retry.
  } else if (error instanceof OpenAI.APIError) {
    console.error(error.status, error.message, error.code);
  } else {
    lanzar error;
  }
}

Registre el ID de solicitud, la marca de tiempo y la zona horaria, el modelo, el endpoint, el estado, el código, el número de reintentos y las características del payload saneado. Nunca registre claves de API ni contenido confidencial de las indicaciones por defecto.

1. 400 Solicitud Incorrecta

La carga útil está mal formada o es incompatible: campo incorrecto, entrada faltante, esquema de herramienta no válido, combinación no admitida o contenido mal codificado. Lea el mensaje, compárelo con la referencia actual de Respuestas y agregue pruebas de contrato. No reintente la entrada sin cambios.

2. Error de autenticación 401

La clave o token es inválido, ha expirado, fue revocado o se envió incorrectamente. Confirma la inyección de secretos y el entorno del proyecto. Rota las claves expuestas; nunca las imprimas mientras depuras.

3. 401 Organización o proyecto incorrecto

Una clave válida puede seguir apuntando al ámbito incorrecto. Verifica la configuración del proyecto y cualquier encabezado explícito de organización/proyecto. Alinea la clave, el recurso y el ámbito de facturación.

4. 401 IP no autorizada

La fuente de la solicitud no coincide con la lista de permitidos configurada. Envíe desde una IP de salida aprobada o actualice la lista de permitidos a través de la administración autorizada. Reintentar desde la misma fuente no tiene ningún efecto.

5. 403 Permiso denegado o región no compatible

El llamante no tiene acceso al recurso, modelo o región. Verifique el rol del proyecto, la disponibilidad del modelo, la propiedad del recurso y las reglas de países admitidos. No disfrace un problema de permisos como "no encontrado" en los registros internos.

6. 404 No Encontrado

Un identificador de respuesta, conversación, almacén vectorial, archivo u otro elemento es incorrecto, ha caducado o es inaccesible. Confirma el ID exacto y el proyecto. Si está dirigido al usuario, evita revelar la existencia de recursos fuera del alcance de ese usuario.

7. 409 Conflicto

Otra solicitud cambió el recurso de manera concurrente. Recargue el estado actual, vuelva a aplicar el cambio previsto contra la nueva versión y utilice bloqueo optimista o idempotencia. Los reintentos inmediatos a ciegas pueden repetir el conflicto.

8. 422 Entidad No Procesable

El formato es sintácticamente aceptable, pero el servicio no puede procesarlo. Valide tamaños, codificaciones, estado del archivo y combinaciones de campos. La tabla oficial sugiere intentarlo de nuevo, pero primero elimine las causas deterministas.

9. Límite de tasa de solicitudes o tokens 429

Ritmo del tráfico y obedece Retry-After cuando esté presente. De lo contrario, usa retroceso exponencial acotado con fluctuación. Coordina los presupuestos de reintentos entre los trabajadores para que no creen una manada atronadora. Reduce llamadas redundantes y grandes ráfagas de tokens.

10. 429 `slow_down`

Esta es una señal de tasa de rampa: el tráfico creció demasiado rápido incluso si los límites principales parecen suficientes. Siga Retry-After, reduzca la tasa de solicitudes, luego aumente gradualmente. La guía actual de OpenAI ofrece una regla general de que después de alcanzar un millón de tokens de entrada por minuto, el crecimiento no debe superar el 50% cada 15 minutos; la activación real varía según el modelo y las condiciones.

11. Límite de crédito, gasto o uso 429

Los códigos incluyen credit_balance_exhausted, organization_spend_limit_exceeded, project_spend_limit_exceeded y organization_usage_limit_exceeded. Estos requieren créditos o cambios de límite. Reintentar no puede restaurar el acceso. Alerte a un propietario y falle rápidamente.

12. 500 Error interno del servidor

Reintentar después de una breve espera con un presupuesto limitado y verificar la página de estado si los fallos persisten. Capturar el ID de solicitud para soporte. Para un flujo de trabajo que cambia de estado, conciliar los efectos secundarios de la herramienta antes de reproducir toda la solicitud.

13. 503 Modelo sobrecargado

El tipo/código documentado es service_unavailable_error / server_is_overloaded. Respete Retry-After o retroceda cuando esté ausente. Tenga en cuenta que la guía actual del SDK de Python distingue RateLimitError para 429 de InternalServerError para 503; capture ambos si su lógica de sobrecarga anterior asumía que cada problema de capacidad era 429.

14. Errores de conexión o tiempo de espera

APIConnectionError puede indicar problemas de red, proxy, certificado TLS, DNS o firewall. APITimeoutError significa que se superó el plazo límite. Reintente las lecturas seguras, inspeccione la configuración del proxy corporativo y evite deshabilitar la verificación TLS. Para escrituras, determine si la operación ocurrió antes de reintentar.

15. Estado de WebSocket y fallos de streaming

previous_response_not_found significa que el estado referenciado no se puede resolver; la guía oficial indica reenviar el contexto de entrada completo con previous_response_id establecido en null. websocket_connection_limit_reached refleja el límite de conexión de 60 minutos; abre una nueva conexión y continúa. También maneja los eventos response.failed, response.incomplete y de transporte error en lugar de asumir que el cierre del socket equivale a la finalización.

Una matriz de reintentos

Intentos de reintento y tiempo total transcurrido de reintento. Utilice un interruptor de circuito durante incidentes generalizados y una ruta de mensajes fallidos para trabajos que requieran revisión del operador. Los reintentos deben ser observables, no ocultos dentro de bucles apilados del SDK y de la aplicación.

Preguntas Frecuentes

¿Debo reintentar cada 429?

No. Los errores de tasa y rampa pueden reintentarse después de la demora requerida; los errores de crédito, gasto y límite de uso requieren acción en la cuenta.

¿Por qué registrar el ID de la solicitud?

Permite que el soporte y su propia telemetría correlacionen una falla con una solicitud de API específica sin exponer la carga útil completa.

¿Puedo reintentar una llamada a herramienta que ha expirado?

Solo después de determinar si causó un efecto secundario. Use claves de idempotencia y conciliación de leer antes de reintentar.

¿Qué deberían ver los usuarios?

Un mensaje conciso y accionable, con una opción segura de reintento cuando corresponda. Mantén los seguimientos de pila, los códigos de proveedor y los detalles sensibles en diagnósticos protegidos.

Conclusión

El manejo confiable de errores de GPT-6 Astra comienza con la clasificación. Corrige solicitudes deterministas 4xx, distingue la presión de tasa de los límites de facturación, retrocede ante fallos transitorios 5xx, reconcilia escrituras inciertas y modela la transmisión como una máquina de estados. Una política de reintentos acotada más una buena telemetría a nivel de solicitud resuelve más incidentes de lo que jamás lograrán los reintentos indiscriminados.