Errores y recuperación

Para obtener información general sobre los errores HTTP y las excepciones del SDK, consulta la guía de códigos de error común a las API.

Cómo examinar un error

Si falla una solicitud, revisa la respuesta HTTP. Si la falla ocurre durante un turno o al configurar el entorno, revisa los eventos y el estado guardado.

Para los errores estructurados, usa error.code en la lógica de la aplicación y error.message para explicar la falla. En los errores de validación de solicitudes, error.param puede indicar qué campo debes corregir. Asegúrate de que el controlador de errores funcione incluso si recibe un código desconocido o si falta param.

En la API beta (OpenAI-Beta: agents=v1), el valor de error de una sesión es una cadena de texto con un mensaje o null. Consulta el evento SSE error asociado para obtener el código de la falla de sesión.

Errores de solicitud a la API

Estos errores se refieren a la solicitud enviada a la API de agentes. Se distinguen de los errores de turno, que se devuelven una vez iniciado el trabajo.

Límites de solicitudes de la API de archivos

Las solicitudes para crear sesiones o adjuntar archivos pueden devolver el código HTTP 429 con files_api_rate_limit_exceeded. La API de agentes verifica los archivos a través de la API de archivos. Estas verificaciones consumen parte de la cuota del usuario autenticado en la API de archivos. Cada archivo adjunto puede requerir una verificación por separado.

12345678{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

Reduce la cantidad de solicitudes simultáneas que acceden a los archivos. Limita el número de intentos y aumenta de forma exponencial el tiempo de espera entre ellos. Si vuelves a intentarlo de inmediato, puedes seguir agotando la cuota.

Esta respuesta HTTP indica que la operación falló. Es un caso distinto al de una sesión o un turno que falla de forma asíncrona después de que la respuesta confirma su creación. Para identificar este error, revisa error.code en lugar de comparar el texto del mensaje.

Errores de turno

Un turno que falló tiene status: "failed" y un objeto error con los campos code y message. Por ejemplo, si el modelo está sobrecargado, puedes recibir lo siguiente:

1234{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

Los códigos de error de turno no tienen un código de estado HTTP propio. Por ejemplo, un turno que falló usa server_overloaded, mientras que una respuesta HTTP puede usar server_is_overloaded.

Errores de sesión y de entorno

Que un turno falle no siempre significa que la sesión haya fallado. Recupera la sesión para determinar si puedes continuar en ella. Si el valor de status es requires_action, atiende las acciones requeridas. Si la sesión falló, corrige la causa y crea una nueva sesión con los datos de entrada que aún necesites.

Recuperación

Cómo volver a intentarlo tras una falla temporal

Usa este procedimiento cuando se alcance un límite de solicitudes, haya una sobrecarga, se agote el tiempo de espera o se produzca una falla temporal del servicio. Si hay problemas con los datos de entrada, las credenciales o los límites de facturación, resuélvelos antes de volver a intentarlo.

1. Verifica el resultado. Si se creó una sesión, recupera la sesión, el turno y los elementos guardados. Si el turno sigue activo, continúa observando su progreso. Si se completó, usa su resultado.
2. Revisa las acciones completadas. Es posible que un turno que falló ya haya modificado archivos o llamado a herramientas externas. Verifica los efectos de esas acciones antes de pedirle al agente que repita el trabajo.
3. Espera y limita los reintentos. Sigue las indicaciones generales para los reintentos, respeta el tiempo indicado por Retry-After en las respuestas HTTP y establece un límite de intentos o un plazo máximo.
4. Repite la solicitud o inicia un nuevo turno. Si recibes un error HTTP, verifica el resultado de la operación original y luego vuelve a intentarla. Si un turno falló, espera a que la sesión esté en estado idle y luego envía un mensaje de seguimiento en el que le pidas al agente que continúe solo con el trabajo pendiente. Así se inicia un nuevo turno en la conversación existente.

Revisa los resultados de las herramientas incluso cuando el turno se complete. Detén los reintentos automáticos si cambia el error o si se alcanza el límite de reintentos.

Cómo corregir datos de entrada no válidos

Corrige el campo que indica error.param o error.message antes de volver a enviar la solicitud.

Si el error se debe al tamaño, reduce el esquema de entrada y salida o el resultado de la herramienta antes de volver a intentarlo. Si la configuración del agente es demasiado grande, crea una nueva sesión con instrucciones y definiciones de herramientas más breves.

Para conocer los requisitos de carga y ver ejemplos, consulta Cómo resolver errores de carga. Si el mensaje indica que hay un problema con una imagen, revisa los datos o la URL de la imagen.

Flujos de eventos desconectados

Ni un evento error ni la desconexión del flujo de eventos confirman el estado final del turno. Sigue los pasos de Cómo recuperar un flujo de eventos desconectado para volver a conectarte y revisar el trabajo guardado antes de reenviar los datos de entrada. Si la sesión recuperada tiene status: "failed" o recibes agent.session.failed, deja de intentar reconectarte y sigue las indicaciones para recuperarte de una falla de sesión.

Si se producen errores persistentes, incluye el ID de la solicitud, el ID de la sesión y el ID del turno en tu solicitud de soporte.