Referencia de errores de la API v2

Consulta todos los códigos de error declarados de la API v2, el estado HTTP correspondiente y su disparador en producción.

Los errores de la API v2 usan un objeto error estructurado:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Algunos errores de validación también incluyen un campo details opcional con información a nivel de campo:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body",
    "details": {
      "fieldErrors": {
        "message": ["Too small: expected string to have >=1 characters"]
      }
    }
  }
}

Cada respuesta de v2 incluye un encabezado x-request-id. Inclúyelo al contactar a soporte. Programa tu lógica contra error.code; los mensajes y los detalles de validación ofrecen contexto legible para humanos.

Catálogo de errores

La tabla incluye los 30 códigos declarados por la API v2. Un guion indica que el código está reservado y no tiene ningún punto de llamada en producción de v2, por lo que actualmente no hay un estado HTTP ni un disparador definidos.

Code	Estado HTTP	Cuándo ocurre	Notas
`VALIDATION_INVALID_BODY`	400	Un cuerpo de solicitud, un valor de ruta, un valor de consulta, un límite, un cursor, un origen de conversación, un tipo de fuente o una entrada de procesamiento de fuente no supera la validación.	`details` solo se incluye cuando el punto de llamada lo proporciona.
`VALIDATION_INVALID_JSON`	400	El endpoint de chat, reintento, resultado de herramienta o comentarios recibe un cuerpo que no es JSON válido.	Los demás endpoints de administración interpretan el JSON con formato incorrecto como un cuerpo inválido.
`AUTH_MISSING_API_KEY`	401	Un endpoint autenticado no recibe ningún encabezado `Authorization` o el valor no comienza con `Bearer` .	El endpoint de verificación de estado no requiere autenticación.
`AUTH_INVALID_API_KEY`	401	No se puede validar la clave de API del bearer.	Usa una clave de API activa del espacio de trabajo.
`AUTH_EXPIRED_API_KEY`	—	Reservado; actualmente ninguna ruta de v2 en producción lo emite.	No hay un estado ni un disparador definidos.
`SUBSCRIPTION_PLAN_REQUIRED`	403	La clave de API es válida, pero su espacio de trabajo no tiene la función de plan `apiAccess`.	El acceso a la API requiere un plan Hobby o superior con facturación activa.
`SUBSCRIPTION_API_RESTRICTED_PLAN`	403	Quien llama habilita el reentrenamiento automático sin acceso de plan, o envía una URL de video sin acceso a la transcripción de video.	La clave de API en sí sigue siendo válida.
`AUTH_INSUFFICIENT_PERMISSIONS`	—	Reservado; actualmente ninguna ruta de v2 en producción lo emite.	No hay un estado ni un disparador definidos.
`AGENT_NOT_FOUND`	404	Una solicitud limitada a un agente indica un agente que no existe o que no pertenece a la cuenta de la clave de API.	Los fallos de propiedad usan la misma respuesta que los agentes inexistentes.
`RESOURCE_NOT_FOUND`	404	No se encuentra una conversación de la API v2 requerida por una operación de detalle, mensaje, reintento o comentarios.	Las operaciones de mutación y de listado de mensajes solo trabajan con conversaciones de la API v2.
`RESOURCE_DOCUMENT_NOT_FOUND`	404	Una eliminación de fuente indica un documento que no existe para el agente.	Los ID de documento inválidos que no son UUID devuelven `VALIDATION_INVALID_BODY` en su lugar.
`RESOURCE_MESSAGE_NOT_FOUND`	404	Los comentarios indican un ID de mensaje inválido o un mensaje que no está en la conversación de la API v2 especificada.	Los ID de mensaje son valores numéricos positivos serializados como strings en las respuestas.
`RESOURCE_MESSAGE_NOT_ASSISTANT`	422	Los comentarios apuntan a un mensaje que no es un mensaje del asistente de IA.	Los mensajes de usuario y los registros de herramientas no pueden recibir comentarios.
`RESOURCE_TOOL_CALL_NOT_FOUND`	404	El endpoint de resultado de herramienta no puede hacer coincidir el `toolCallId` proporcionado con una acción pendiente del cliente.	La llamada es desconocida, ha caducado o pertenece a otra conversación de API v2.
`QUOTA_CHATBOT_LIMIT`	403	Crear el agente superaría el límite de agentes del espacio de trabajo.	Elimina un agente o mejora tu plan antes de volver a intentarlo.
`QUOTA_STORAGE_LIMIT`	403	El procesamiento de una fuente de texto o de preguntas y respuestas reporta un límite de almacenamiento, una URL nueva no cabe en el almacenamiento disponible, o la creación del trabajo de URL reporta un fallo de cuota.	Reentrenar una URL existente no consume almacenamiento de documentos adicional.
`CHAT_MODEL_NOT_ALLOWED`	403	Una actualización de la configuración de IA selecciona un modelo no disponible en el plan del espacio de trabajo.	Elige un modelo permitido o mejora el plan.
`CHAT_CREDITS_EXHAUSTED`	—	Reservado; actualmente ninguna ruta de v2 en producción lo emite.	No hay un estado ni un disparador definidos.
`CHAT_AGENT_CREDITS_EXHAUSTED`	—	Reservado; actualmente ninguna ruta de v2 en producción lo emite.	No hay un estado ni un disparador definidos.
`CHAT_CONVERSATION_MISMATCH`	404	Una solicitud de chat proporciona un `conversationId` bien formado (≤128 caracteres) que no corresponde a ninguna conversación de la API v2 del agente.	Un `conversationId` de más de 128 caracteres se rechaza antes con `400 VALIDATION_INVALID_BODY`, no con este código. Si se omite `conversationId`, se inicia una conversación nueva.
`CHAT_RETRY_MESSAGE_NOT_FOUND`	404	El reintento recibe un ID de mensaje no positivo o no entero, o el objetivo no es un mensaje del asistente de IA en la conversación de la API v2.	Los registros de herramientas no pueden ser objetivo de un reintento.
`CHAT_RETRY_NO_USER_MESSAGE`	400	El objetivo del reintento no tiene un mensaje de usuario anterior para reproducir.	El reintento regenera a partir del turno de usuario inmediatamente anterior a la respuesta del asistente seleccionada.
`INSTAGRAM_NOT_CONNECTED`	404	Una solicitud del canal de Instagram indica un agente sin conexión de Instagram.	`GET /channels/instagram` responde con `{ "connected": false }` en lugar de este código.
`INSTAGRAM_RECONNECT_REQUIRED`	409	La conversión de comentarios en mensajes directos se activa sin el permiso de comentarios, o se publican iniciadores de conversación en una conexión cuyo estado no es `connected`.	Vuelve a conectar la cuenta en Publicar → Instagram en el panel.
`INSTAGRAM_AUTOMATION_TARGET_TAKEN`	409	Una automatización `comment_to_dm` o `story_leads` se activa mientras otra instancia activa ya apunta a la misma publicación o historia.	Desactiva la otra instancia o elige otra publicación o historia. Los borradores nunca se rechazan.
`INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS`	409	Una automatización general `comment_to_dm` o `story_leads` (`postScope` / `storyScope` `"any"`) se activa mientras ya existe otra automatización general activa del mismo tipo.	Desactiva primero la automatización general existente o elige una publicación o historia específica.
`INSTAGRAM_SYNC_IN_PROGRESS`	409	Un `PATCH` del menú persistente o de los iniciadores de conversación coincide con una sincronización del mismo recurso y agente.	Reintenta cuando termine la publicación o eliminación activa.
`INSTAGRAM_SYNC_FAILED`	502	Falló la sincronización del menú persistente o de los iniciadores de conversación.	`details.code` es un código de error permitido; `details.http_status` y `details.meta_code` son numéricos o `null`. El texto del mensaje de Meta nunca se devuelve, y la instantánea activa almacenada sigue describiendo el último estado confirmado.
`RATE_LIMIT_TOO_MANY_REQUESTS`	—	Reservado; actualmente ninguna ruta de v2 en producción lo emite.	No hay definido ningún tiempo de reintento ni comportamiento de `Retry-After`.
`INTERNAL_SERVER_ERROR`	500	La creación del trabajo de URL falla por un motivo distinto a la cuota, o un reintento sin streaming no produce ningún mensaje del asistente persistido.	Incluye `x-request-id` al reportar el fallo.

Referencia de errores de la API v2

Consulta todos los códigos de error declarados de la API v2, el estado HTTP correspondiente y su disparador en producción.

Catálogo de errores

Referencia relacionada