Pular para o conteúdo principal
Este artigo ajudará você a compreender os erros de API mais comuns que podem ser encontrados ao utilizar a plataforma cloud do EKB. Você encontrará detalhes sobre os diversos códigos de status HTTP e códigos de erro específicos, fornecendo as etapas essenciais de solução de problemas para resolver esses problemas de forma eficaz. Ao compreender o formato de resposta de erro e os problemas comuns associados ao uso de API, você estará mais preparado para lidar com erros e aprimorar sua experiência de desenvolvimento.

​
Formato de Resposta de Erro

Todos os erros de API seguem um formato consistente: 
{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "detail": "Additional error details (optional)"
}
Alguns erros também podem incluir:
  • error_id: Identificador único para rastreamento do erro
  • invalid_fields: Lista de campos que falharam na validação (para erros de validação)

​
Códigos de Status HTTP

​
400 Bad Request

Erros do lado do cliente devido a entrada inválida ou solicitações mal formatadas.
Código de Erro: VALIDATION_ERROR Código de Status: 400Descrição: Falha na validação da solicitação. Um ou mais campos na solicitação são inválidos.Causas Comuns:
  • Campos obrigatórios ausentes
  • Formato de campo inválido (por exemplo, e-mail inválido, formato de data)
  • Valores de campo fora do intervalo permitido
  • Tipos de dados inválidos
Exemplo de Resposta:
{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "invalid_fields": ["email", "project_id"]
  }
}
Solução de Problemas:
  1. Revise o array invalid_fields para identificar os campos problemáticos
  2. Verifique os requisitos dos campos na documentação da API
  3. Confirme se os tipos de dados correspondem aos formatos esperados
  4. Certifique-se de que todos os campos obrigatórios foram fornecidos
Código de Erro: INVALID_API_KEY
Código de Status: 400Descrição: A chave de API fornecida é inválida ou mal formatada.Solução de Problemas:
  1. Verifique se a chave de API foi copiada corretamente (sem espaços extras)
  2. Verifique se a chave de API está ativa em Minha Conta > Chaves de API
  3. Certifique-se de estar usando a chave de API correta para seu ambiente
  4. Regenere a chave de API se necessário
Código de Erro: INVALID_CREDENTIALS
Código de Status: 400Descrição: As credenciais de autenticação são inválidas.Solução de Problemas:
  1. Verifique se o e-mail e a senha estão corretos
  2. Verifique se a conta está bloqueada ou desativada
  3. Tente redefinir sua senha
  4. Certifique-se de estar usando o método de autenticação correto
Código de Erro: INVALID_OR_EXPIRED_JWT_TOKEN
Código de Status: 400Descrição: O token JWT é inválido, expirado ou mal formatado.Solução de Problemas:
  1. Atualize seu token de autenticação
  2. Faça logout e faça login novamente
  3. Verifique o tempo de expiração do token
  4. Confirme se o token está sendo enviado no formato de cabeçalho correto

​
401 Unauthorized

Autenticação necessária ou falha na autenticação.
Código de Erro: AUTHENTICATION
Código de Status: 401Descrição: Autenticação necessária para acessar este recurso.Solução de Problemas:
  1. Certifique-se de estar conectado
  2. Verifique se sua sessão expirou
  3. Confirme se os cabeçalhos de autenticação estão incluídos na solicitação
  4. Reautentique-se se necessário
Código de Erro: INVALID_BEARER_TOKEN
Código de Status: 401Descrição: O token Bearer fornecido é inválido.Solução de Problemas:
  1. Verifique o formato do token: Bearer <token>
  2. Verifique se o token expirou
  3. Regenere o token de autenticação
  4. Certifique-se de que o token não foi revogado
Código de Erro: EMAIL_IS_NOT_VERIFIED
Código de Status: 401Descrição: O endereço de e-mail não foi verificado.Solução de Problemas:
  1. Verifique seu e-mail para o link de verificação
  2. Solicite um novo e-mail de verificação
  3. Confirme se o endereço de e-mail está correto
  4. Verifique a pasta de spam/lixeira

​
403 Forbidden

Acesso negado devido a permissões insuficientes.
Código de Erro: AUTHORIZATION
Código de Status: 403Descrição: Você não tem permissão para realizar esta ação.Solução de Problemas:
  1. Verifique se você tem a função/permissão necessária
  2. Verifique se você é membro do projeto/equipe
  3. Entre em contato com o administrador do projeto/equipe para conceder acesso
  4. Certifique-se de estar acessando o recurso correto
Código de Erro: PERMISSION_DENIED
Código de Status: 403Descrição: Permissão negada para a operação solicitada.Solução de Problemas:
  1. Revise sua função de usuário e permissões
  2. Verifique as configurações de acesso do projeto/equipe
  3. Confirme a propriedade do recurso
  4. Entre em contato com o administrador para obter acesso
Código de Erro: DOMAIN_NOT_ALLOWED
Código de Status: 403Descrição: Seu domínio de e-mail não é permitido para esta operação.Solução de Problemas:
  1. Verifique se seu domínio de e-mail está na lista de permissões
  2. Entre em contato com o administrador para adicionar seu domínio
  3. Use um endereço de e-mail permitido

​
404 Not Found

O recurso solicitado não existe.
Código de Erro: ENTITY_NOT_FOUND
Código de Status: 404Descrição: O recurso solicitado não foi encontrado.Cenários Comuns:
  • Projeto não encontrado
  • Agente não encontrado
  • Documento não encontrado
  • Usuário não encontrado
Solução de Problemas:
  1. Verifique se o ID do recurso está correto
  2. Verifique se o recurso foi excluído
  3. Certifique-se de ter acesso ao recurso
  4. Confirme se está usando o projeto/espaço de trabalho correto
Código de Erro: FILE_NOT_FOUND
Código de Status: 404Descrição: O arquivo solicitado não existe.Solução de Problemas:
  1. Verifique se o ID ou caminho do arquivo está correto
  2. Verifique se o arquivo foi excluído
  3. Certifique-se de que o arquivo está no local esperado
  4. Verifique as permissões do arquivo
Código de Erro: FLOW_NOT_FOUND
Código de Status: 404Descrição: O fluxo de trabalho/fluxo solicitado não foi encontrado.Solução de Problemas:
  1. Verifique se o ID do fluxo está correto
  2. Verifique se o fluxo foi excluído
  3. Certifique-se de ter acesso ao fluxo
  4. Confirme se o fluxo existe no projeto atual
Código de Erro: CONFIG_NOT_FOUND
Código de Status: 404Descrição: A configuração necessária não foi encontrada.Solução de Problemas:
  1. Verifique se a configuração existe
  2. Verifique a configuração nas definições
  3. Certifique-se de que os serviços necessários estão configurados
  4. Revise a documentação de configuração

​
500 Internal Server Error

Erros do lado do servidor que requerem investigação.
Código de Erro: ENGINE_OPERATION_FAILURE
Código de Status: 500Descrição: Uma operação interna do motor falhou.Solução de Problemas:
  1. Tente novamente a solicitação após alguns instantes
  2. Verifique o status do sistema em status.getodin.ai
  3. Se persistir, entre em contato com o suporte fornecendo detalhes do erro
  4. Forneça o ID do erro se disponível
Código de Erro: EXTERNAL_SERVICE
Código de Status: 500Descrição: Um serviço externo necessário para esta operação falhou.Cenários Comuns:
  • Falha na API do provedor de LLM
  • Falha em integração de terceiros (Google Drive, Slack, etc.)
  • Tempo limite da API externa
Solução de Problemas:
  1. Verifique o status do serviço externo
  2. Verifique as chaves de API/credenciais para serviços externos
  3. Tente novamente a solicitação
  4. Verifique a configuração da integração
  5. Entre em contato com o suporte se o problema persistir
Código de Erro: INFRASTRUCTURE
Código de Status: 500Descrição: Erro de infraestrutura (banco de dados, armazenamento, etc.).Solução de Problemas:
  1. Tente novamente a solicitação
  2. Verifique o status do sistema
  3. Se persistir, entre em contato com o suporte
  4. Forneça detalhes do erro e marca de tempo
Código de Erro: OPEN_AI_FAILED
Código de Status: 500Descrição: Chamada à API do OpenAI falhou.Solução de Problemas:
  1. Verifique o status do serviço OpenAI
  2. Verifique se a chave de API é válida e possui créditos
  3. Verifique os limites de taxa
  4. Tente novamente com backoff exponencial
  5. Verifique a disponibilidade do modelo

​
503 Service Unavailable

Serviço temporariamente indisponível.
Código de Erro: EXECUTION_TIMEOUT
Código de Status: 503Descrição: A operação atingiu o tempo limite.Solução de Problemas:
  1. Tente novamente a solicitação
  2. Simplifique a operação se possível
  3. Verifique se o sistema está sob alta carga
  4. Divida operações grandes em operações menores
  5. Entre em contato com o suporte se o tempo limite persistir

​
Erros de Lógica de Negócio

Código de Erro: QUOTA_EXCEEDED
Código de Status: 400 ou 429Descrição: Você excedeu seu limite de cota.Solução de Problemas:
  1. Verifique seu uso atual em Minha Conta > Painel
  2. Revise os limites da assinatura
  3. Atualize seu plano se necessário
  4. Aguarde o período de redefinição da cota
  5. Entre em contato com vendas para aumento de cota
Código de Erro: FEATURE_DISABLED
Código de Status: 400Descrição: Esta funcionalidade está desativada para sua conta.Solução de Problemas:
  1. Verifique seu plano de assinatura
  2. Confirme a disponibilidade da funcionalidade
  3. Atualize o plano se a funcionalidade requer um nível superior
  4. Entre em contato com o suporte para acesso à funcionalidade
Código de Erro: FLOW_IN_USE
Código de Status: 400Descrição: O fluxo de trabalho está atualmente em uso e não pode ser modificado.Solução de Problemas:
  1. Aguarde as execuções ativas serem concluídas
  2. Cancele as execuções ativas do fluxo de trabalho
  3. Verifique o status de execução do fluxo de trabalho
  4. Tente novamente após as execuções serem concluídas
Código de Erro: EXISTING_USER
Código de Status: 400Descrição: Já existe um usuário com este e-mail.Solução de Problemas:
  1. Tente fazer login em vez de se cadastrar
  2. Use a redefinição de senha se esqueceu as credenciais
  3. Use um endereço de e-mail diferente
  4. Entre em contato com o suporte se precisar de recuperação de conta

​
Erros Específicos de Integração

Código de Erro: INVALID_APP_CONNECTION
Código de Status: 400Descrição: Conexão de aplicativo inválida ou expirada (integração OAuth).Solução de Problemas:
  1. Reautentique a integração
  2. Verifique a expiração do token OAuth
  3. Verifique as credenciais da integração
  4. Reconecte a integração nas configurações
Código de Erro: INVALID_SAML_RESPONSE
Código de Status: 400Descrição: Resposta SAML inválida do provedor de SSO.Solução de Problemas:
  1. Verifique a configuração do SSO
  2. Verifique a URL de metadados SAML
  3. Certifique-se de que o provedor de SSO está acessível
  4. Entre em contato com o suporte para revisão da configuração do SSO
Código de Erro: RATE_LIMITED ou ratelimited
Código de Status: 429Descrição: Limite de taxa da API excedido.Solução de Problemas:
  1. Aguarde a janela de limite de taxa ser redefinida
  2. Implemente backoff exponencial
  3. Reduza a frequência de solicitações
  4. Verifique os cabeçalhos de limite de taxa na resposta
  5. Atualize o plano para limites de taxa mais altos

​
Obtendo Ajuda

Se você encontrar um erro que não está listado aqui ou precisar de assistência:
  1. Verifique os Detalhes do Erro: Anote o código de erro, a mensagem e o error_id
  2. Verifique o Status do Sistema: Acesse status.getodin.ai para problemas conhecidos
  3. Revise a Documentação: Verifique a documentação relevante da API
  4. Entre em Contato com o Suporte: Envie um e-mail para o Suporte com:
    • Código de erro e mensagem
    • ID do erro (se disponível)
    • Etapas para reproduzir
    • Detalhes da solicitação/resposta (sanitizados)
    • Marca de tempo do erro