Documentação

Referência de Erros da API v2

Consulte todos os códigos de erro declarados da API v2, os status HTTP e os gatilhos de produção.

Os erros da API v2 usam um objeto error estruturado:

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

Alguns erros de validação também incluem um campo opcional details com informações no nível de campo:

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

Toda resposta v2 inclui um header x-request-id. Inclua esse valor ao contatar o suporte. Programe usando error.code; as mensagens e os detalhes de validação fornecem contexto legível para humanos.

Catálogo de Erros

A tabela inclui todos os 30 códigos declarados pela API v2. Um traço significa que o código está reservado e não possui nenhum ponto de chamada em produção na v2, portanto nenhum status HTTP ou gatilho está definido atualmente.

CódigoStatus HTTPQuando aconteceObservações
VALIDATION_INVALID_BODY400Um corpo de requisição, valor de caminho, valor de consulta, limite, cursor, fonte de conversa, tipo de fonte ou entrada de processamento de fonte falha na validação.details é incluído apenas quando o ponto de chamada o fornece.
VALIDATION_INVALID_JSON400O endpoint de chat, retry, resultado de ferramenta ou feedback recebe um corpo que não é um JSON válido.Outros endpoints de gerenciamento tratam JSON malformado como um corpo inválido.
AUTH_MISSING_API_KEY401Um endpoint autenticado não recebe nenhum header Authorization ou o valor não começa com Bearer .O endpoint de health é não autenticado.
AUTH_INVALID_API_KEY401A chave de API do tipo bearer não pode ser validada.Use uma chave de API de workspace ativa.
AUTH_EXPIRED_API_KEY—Reservado; atualmente não é emitido por nenhuma rota v2 em produção.Nenhum status ou gatilho está definido.
SUBSCRIPTION_PLAN_REQUIRED403A chave de API é válida, mas o workspace dela não possui o recurso de plano apiAccess.O acesso à API requer um plano Hobby ou superior com faturamento ativo.
SUBSCRIPTION_API_RESTRICTED_PLAN403Um solicitante habilita o retreinamento automático sem acesso ao plano, ou envia uma URL de vídeo sem acesso à transcrição de vídeo.A chave de API em si permanece válida.
AUTH_INSUFFICIENT_PERMISSIONS—Reservado; atualmente não é emitido por nenhuma rota v2 em produção.Nenhum status ou gatilho está definido.
AGENT_NOT_FOUND404Uma requisição vinculada a um agente nomeia um agente que não existe ou não é de propriedade da conta da chave de API.Falhas de propriedade usam a mesma resposta de agentes ausentes.
RESOURCE_NOT_FOUND404Uma conversa da API v2 exigida por uma operação de detalhe, mensagem, retry ou feedback não pode ser encontrada.As operações de mutação e de listagem de mensagens só se referem a conversas da API v2.
RESOURCE_DOCUMENT_NOT_FOUND404A exclusão de uma fonte nomeia um documento que não existe para o agente.IDs de documento inválidos que não são UUID retornam VALIDATION_INVALID_BODY em vez disso.
RESOURCE_MESSAGE_NOT_FOUND404O feedback nomeia um ID de mensagem inválido ou uma mensagem que não está na conversa da API v2 especificada.IDs de mensagem são valores numéricos positivos serializados como strings nas respostas.
RESOURCE_MESSAGE_NOT_ASSISTANT422O feedback tem como alvo uma mensagem que não é uma mensagem do assistente de IA.Mensagens de usuário e registros de ferramenta não podem receber feedback.
RESOURCE_TOOL_CALL_NOT_FOUND404O endpoint de resultado de ferramenta não consegue corresponder o toolCallId fornecido a uma ação pendente do cliente.A chamada é desconhecida, expirou ou pertence a outra conversa da API v2.
QUOTA_CHATBOT_LIMIT403A criação de um agente excederia o limite de chatbots do workspace.Exclua um agente ou faça upgrade antes de tentar novamente.
QUOTA_STORAGE_LIMIT403O processamento de fonte de texto ou Q&A reporta um limite de armazenamento, uma nova URL não cabe dentro do armazenamento, ou a criação de job de URL reporta uma falha de cota.Retreinar uma URL existente não consome novo armazenamento de documento.
CHAT_MODEL_NOT_ALLOWED403Uma atualização de configurações de IA seleciona um modelo indisponível no plano do workspace.Escolha um modelo permitido ou faça upgrade do plano.
CHAT_CREDITS_EXHAUSTED—Reservado; atualmente não é emitido por nenhuma rota v2 em produção.Nenhum status ou gatilho está definido.
CHAT_AGENT_CREDITS_EXHAUSTED—Reservado; atualmente não é emitido por nenhuma rota v2 em produção.Nenhum status ou gatilho está definido.
CHAT_CONVERSATION_MISMATCH404Uma requisição de chat fornece um conversationId bem formado (≤128 caracteres) que não corresponde a uma conversa da API v2 para o agente.Um conversationId com mais de 128 caracteres é rejeitado antes, com 400 VALIDATION_INVALID_BODY, não com este código. Omitir conversationId inicia uma nova conversa.
CHAT_RETRY_MESSAGE_NOT_FOUND404O retry recebe um ID de mensagem não positivo/não inteiro, ou o alvo não é uma mensagem do assistente de IA na conversa da API v2.Registros de ferramenta não são alvos de retry.
CHAT_RETRY_NO_USER_MESSAGE400O alvo do retry não tem nenhuma mensagem de usuário anterior para reproduzir.O retry regenera a partir do turno do usuário imediatamente anterior à resposta do assistente selecionada.
INSTAGRAM_NOT_CONNECTED404Uma requisição de canal do Instagram nomeia um agente sem conexão com o Instagram.GET /channels/instagram responde com { "connected": false } em vez deste código.
INSTAGRAM_RECONNECT_REQUIRED409A conversão de comentário em DM é ativada sem a permissão de comentários, ou iniciadores de conversa são publicados em uma conexão que não está connected.Reconecte a conta em Publicar → Instagram no painel.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409Uma automação comment_to_dm ou story_leads é ativada enquanto outra instância ativa já tem como alvo a mesma publicação ou o mesmo story.Desative a outra instância ou escolha outra publicação ou outro story. Rascunhos nunca são rejeitados.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409Uma automação genérica comment_to_dm ou story_leads (postScope / storyScope "any") é ativada enquanto já existe uma automação genérica ativa desse tipo.Primeiro, desative a automação genérica existente ou escolha uma publicação ou um story específico.
INSTAGRAM_SYNC_IN_PROGRESS409Um PATCH do menu persistente ou dos iniciadores de conversa coincide com uma sincronização do mesmo recurso e agente.Tente novamente quando a publicação ou remoção ativa terminar.
INSTAGRAM_SYNC_FAILED502A sincronização do menu persistente ou dos iniciadores de conversa falhou.details.code é um código de falha permitido; details.http_status e details.meta_code são numéricos ou null. O texto da mensagem da Meta nunca é retornado, e o instantâneo ativo armazenado ainda descreve o último estado confirmado.
RATE_LIMIT_TOO_MANY_REQUESTS—Reservado; atualmente não é emitido por nenhuma rota v2 em produção.Nenhum tempo de retry ou comportamento de Retry-After está definido.
INTERNAL_SERVER_ERROR500A criação de job de URL falha por um motivo não relacionado a cota, ou um retry sem streaming não produz nenhuma mensagem de assistente persistida.Inclua x-request-id ao reportar a falha.

Referências Relacionadas