Errores de la API

En esta página, se proporciona una referencia para todos los códigos de error de la API de Interactions, se describe el formato de respuesta de error y se explica cómo la API entrega errores para diferentes tipos de solicitudes.

Códigos de error estándar de la API

Estos códigos de error generales a nivel de la solicitud corresponden a códigos de estado HTTP estándar. Usa el campo code en la lógica de tu aplicación para controlar los errores de forma programática.

Código Estado de HTTP Descripción Acción recomendada
invalid_request 400 Bad Request La solicitud tiene un formato incorrecto o contiene parámetros no válidos. Compara tus entradas con la referencia de la API.
parameter_unknown 400 Bad Request La solicitud contiene un parámetro desconocido. Quita el parámetro no reconocido y vuelve a intentarlo.
authentication 401 Sin autorización Falta la clave de API o no es válida. Verifica tu clave de API.
permission_denied 403 Forbidden Tu clave de API no tiene permiso para este recurso. Verifica los permisos de tu clave de API y el acceso al proyecto.
not_found 404 No encontrado No se encontró el recurso solicitado. Verifica la ruta de acceso y los parámetros del recurso.
model_not_found 404 No encontrado No se encontró el modelo especificado. Verifica el nombre del modelo o vuelve a un modelo diferente.
rate_limit_exceeded 429 Too Many Requests Excediste el límite de solicitudes o tokens por minuto o por segundo. Espera y vuelve a intentarlo con una retirada exponencial.
quota_exceeded 429 Too Many Requests Excediste tu cuota diaria. Espera hasta que se restablezca la cuota o solicita un aumento de cuota.
cancelled 499 Client Closed Request El cliente canceló la solicitud antes de que se completara. No se requiere ninguna acción. Por lo general, esto significa que el cliente se desconectó.
api_error 500 Internal Server Error Se produjo un error inesperado en el servidor. Reintenta la solicitud. Si el problema persiste, comunícate con el equipo de asistencia.
service_unavailable 503 Service Unavailable El servicio está sobrecargado o inactivo temporalmente. Espera y vuelve a intentarlo con una retirada exponencial.

Códigos de generación bloqueados

Estos códigos de error indican que las restricciones de política, seguridad o contenido bloquearon el resultado del modelo. Cuando recibas uno de estos códigos, modifica tu entrada y vuelve a intentarlo.

Código Descripción
safety Las infracciones de seguridad (contenido dañino) bloquearon la solicitud.
recitation Las restricciones de derechos de autor o recitación bloquearon la solicitud.
language Un idioma no admitido bloqueó la solicitud.
prohibited_content Los lineamientos sobre contenido prohibido bloquearon la solicitud.
spii Las restricciones de información de identificación personal sensible bloquearon la solicitud.
blocklist Los términos prohibidos en una lista de bloqueo bloquearon la solicitud.
image_safety Las infracciones de seguridad bloquearon la generación de imágenes.
image_prohibited_content Los lineamientos sobre contenido prohibido bloquearon la generación de imágenes.
image_recitation Las restricciones de derechos de autor o recitación bloquearon la generación de imágenes.
image_other Motivos no especificados bloquearon la generación de imágenes.
content_blocked Un motivo de política no especificado bloqueó la solicitud.

Códigos de error de generación

Estos códigos de error indican un problema estructural con el resultado generado del modelo (como una llamada a función con formato incorrecto o una llamada a herramienta no declarada).

Código Descripción
malformed_function_call El modelo produjo una llamada a función que no se pudo analizar.
malformed_tool_call El modelo produjo una llamada a herramienta que no se pudo analizar.
unexpected_tool_call El modelo llamó a una herramienta que no se declaró en la solicitud.
no_image El modelo no pudo generar una imagen.
too_many_tool_calls El modelo generó más llamadas a herramientas de las permitidas.
missing_thought_signature La respuesta no tiene una firma de pensamiento obligatoria.

Formato de respuesta de error

Todos los errores de la API de Interactions muestran un error que contiene un code y un message. Por ejemplo, pasar un tipo de herramienta no admitido muestra lo siguiente:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Campo Tipo Descripción
code string Un código de error procesable en snake_case.
message string Una descripción legible por humanos de lo que salió mal.

Cómo se entregan los errores

La API entrega errores de manera diferente según si realizas una solicitud HTTP estándar o una solicitud de transmisión (SSE).

Solicitudes HTTP estándar

Para las solicitudes estándar (sin transmisión), la API establece el código de estado de respuesta HTTP (como 400 Bad Request, 401 Unauthorized o 429 Too Many Requests) y muestra un objeto error en el cuerpo de la respuesta JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Solicitudes de transmisión (SSE)

Para las solicitudes de transmisión (stream: true), la API envía eventos de error a través de la transmisión de eventos enviados por el servidor (SSE) con event_type configurado como "error". El campo error contiene la misma estructura code y message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Para obtener el esquema completo de eventos SSE, consulta la referencia de la API de Interactions.

¿Qué sigue?