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 de la API estándar

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 errores de forma programática.

Código Estado de HTTP Descripción Acción recomendada
invalid_request 400 Bad Request La carga útil de la solicitud tiene un formato incorrecto o contiene parámetros no válidos. Comprueba la sintaxis y los parámetros de tu solicitud en la referencia de la API.
failed_precondition 400 Bad Request No se puede procesar la solicitud porque no se cumple un requisito previo (por ejemplo, la facturación está inhabilitada). Verifica el estado de facturación del proyecto o los requisitos previos de la cuenta.
out_of_range 416 Requested Range Not Satisfiable El parámetro de la solicitud está fuera del rango válido. Comprueba los valores y límites de los parámetros.
parameter_unknown 400 Bad Request La solicitud contiene un parámetro desconocido. Quita el parámetro no reconocido y vuelve a intentarlo.
authentication 401 Unauthorized Falta la clave de API, no es válida o venció. Verifica tu clave de API.
payment_required Se requiere un pago (402 Payment Required) Se agotó tu saldo de crédito de prepago. Agrega créditos a tu cuenta de facturación o activa la recarga automática. No se reintenta: La solicitud no se completará hasta que se agreguen créditos.
permission_denied 403 Forbidden Tu clave de API no tiene permiso para acceder a 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 recurre a otro.
already_exists 409 Conflict La entidad que intentaste crear ya existe. Verifica si el recurso ya existe antes de volver a crearlo.
aborted 409 Conflict La operación se anuló debido a un conflicto o a una falla en la verificación de simultaneidad. Vuelve a intentar enviar la solicitud en un nivel de aplicación más alto.
rate_limit_exceeded 429 Too Many Requests Superaste 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 Superaste tu cuota diaria. Espera a que se restablezca la cuota o solicita un aumento.
too_many_requests 429 Too Many Requests Realizaste demasiadas solicitudes en un período corto. Espera y vuelve a intentarlo con una retirada exponencial.
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.
unimplemented 501, Not Implemented La operación o la función no se implementaron o no se admiten. Verifica las capacidades de la API o cambia a una función compatible.
service_unavailable 503 Service Unavailable El servicio está temporalmente sobrecargado o inactivo. Espera y vuelve a intentarlo con una retirada exponencial.
deadline_exceeded 504 Gateway Timeout La solicitud no finalizó dentro del plazo. Quita o aumenta la configuración del plazo del cliente para usar el valor predeterminado del servidor.

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 La solicitud se bloqueó debido a restricciones de derechos de autor o de recitación.
language Un idioma no admitido bloqueó la solicitud.
prohibited_content Los lineamientos sobre contenido prohibido bloquearon la solicitud.
spii Las restricciones sobre la información de identificación personal sensible bloquearon la solicitud.
blocklist La solicitud se bloqueó debido a términos prohibidos en una lista de bloqueo.
image_safety Los incumplimientos 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 de recitación bloquearon la generación de imágenes.
image_other Se bloqueó la generación de imágenes por motivos no especificados.
content_blocked La solicitud se bloqueó por un motivo de política no especificado.

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 mal formada 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 la 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 Falta una firma de pensamiento obligatoria en la respuesta.

Formato de respuesta de error

Todos los errores de la API de Interactions devuelven un objeto error que contiene un code y un message. Por ejemplo, si se pasa un tipo de herramienta no compatible, se devuelve 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 Es un código de error legible por máquina en snake_case.
message string Es 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 (no de 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 devuelve 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 establecido en "error". El campo error contiene la misma estructura de code y message:

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

Para ver el esquema completo de eventos enviados por el servidor, consulta la referencia de la API de Interactions.

¿Qué sigue?