Errores de la API

En esta página, se proporciona una referencia de 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 los errores de manera 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. Verifica la sintaxis y los parámetros de tu solicitud con 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. Verifica los valores y los 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 402 Pago requerido Se agotó tu crédito disponible de prepago. Agrega créditos a tu cuenta de facturación o activa la recarga automática. No vuelvas a intentarlo: la solicitud no se completará hasta que se agreguen créditos.
permission_denied 403 Forbidden Tu clave de API no tiene permiso para este recurso o el acceso a la API de tu proyecto está restringido. Verifica los permisos de tu clave de API, la elegibilidad del nivel del proyecto y el estado de facturación. Consulta Cómo solucionar problemas de proyectos restringidos o no disponibles.
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 un error en la verificación de simultaneidad. Vuelve a intentar ejecutar 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 breve. Espera y vuelve a intentarlo con una retirada exponencial.
cancelled 499 Solicitud cerrada por el cliente 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 Error interno del servidor Se produjo un error inesperado en el servidor. Reintenta la solicitud. Si el problema persiste, comunícate con el equipo de asistencia.
unimplemented 501 No implementado La operación o función no se implementó o no se admite. Verifica las capacidades de la API o cambia a una función compatible.
service_unavailable 503 Service Unavailable El servicio está sobrecargado o inactivo de forma temporal. Espera y vuelve a intentarlo con una retirada exponencial.
deadline_exceeded 504 Gateway Timeout La solicitud no finalizó dentro del plazo. Quita o aumenta el parámetro de configuración de la fecha límite del cliente para usar el valor predeterminado del servidor.

Códigos bloqueadores de generación

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 Los incumplimientos de seguridad (contenido dañino) bloquearon la solicitud.
recitation Las restricciones de derechos de autor o de recitación bloquearon la solicitud.
language Un idioma no admitido bloqueó la solicitud.
prohibited_content Los lineamientos de 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 entidades bloqueadas bloquearon la solicitud.
image_safety Se bloqueó la generación de imágenes debido a incumplimientos de seguridad.
image_prohibited_content Los lineamientos de 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 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 por el modelo (como una llamada a función con formato incorrecto o una llamada a una 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 A la respuesta le falta una firma de pensamiento obligatoria.

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 pasas 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 Un código de error legible por máquinas 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

En el caso de las solicitudes estándar (sin transmisión), la API establece el código de estado de la 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)

En el caso de 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 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 de SSE, consulta la referencia de la API de Interactions.

¿Qué sigue?