Erros Comuns de API

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.

VALIDATION_ERROR

Código de Erro: VALIDATION_ERROR Código de Status: 400

Descriçã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

INVALID_API_KEY

Código de Erro: INVALID_API_KEY
Código de Status: 400

Descriçã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

INVALID_CREDENTIALS

Código de Erro: INVALID_CREDENTIALS
Código de Status: 400

Descriçã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

INVALID_OR_EXPIRED_JWT_TOKEN

Código de Erro: INVALID_OR_EXPIRED_JWT_TOKEN
Código de Status: 400

Descriçã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.

AUTHENTICATION

Código de Erro: AUTHENTICATION
Código de Status: 401

Descriçã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

INVALID_BEARER_TOKEN

Código de Erro: INVALID_BEARER_TOKEN
Código de Status: 401

Descriçã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

EMAIL_IS_NOT_VERIFIED

Código de Erro: EMAIL_IS_NOT_VERIFIED
Código de Status: 401

Descriçã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.

AUTHORIZATION

Código de Erro: AUTHORIZATION
Código de Status: 403

Descriçã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

PERMISSION_DENIED

Código de Erro: PERMISSION_DENIED
Código de Status: 403

Descriçã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

DOMAIN_NOT_ALLOWED

Código de Erro: DOMAIN_NOT_ALLOWED
Código de Status: 403

Descriçã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.

ENTITY_NOT_FOUND

Código de Erro: ENTITY_NOT_FOUND
Código de Status: 404

Descriçã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

FILE_NOT_FOUND

Código de Erro: FILE_NOT_FOUND
Código de Status: 404

Descriçã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

FLOW_NOT_FOUND

Código de Erro: FLOW_NOT_FOUND
Código de Status: 404

Descriçã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

CONFIG_NOT_FOUND

Código de Erro: CONFIG_NOT_FOUND
Código de Status: 404

Descriçã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.

ENGINE_OPERATION_FAILURE

Código de Erro: ENGINE_OPERATION_FAILURE
Código de Status: 500

Descriçã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

EXTERNAL_SERVICE

Código de Erro: EXTERNAL_SERVICE
Código de Status: 500

Descriçã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

INFRASTRUCTURE

Código de Erro: INFRASTRUCTURE
Código de Status: 500

Descriçã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

OPEN_AI_FAILED

Código de Erro: OPEN_AI_FAILED
Código de Status: 500

Descriçã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.

EXECUTION_TIMEOUT

Código de Erro: EXECUTION_TIMEOUT
Código de Status: 503

Descriçã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

QUOTA_EXCEEDED

Código de Erro: QUOTA_EXCEEDED
Código de Status: 400 ou 429

Descriçã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

FEATURE_DISABLED

Código de Erro: FEATURE_DISABLED
Código de Status: 400

Descriçã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

FLOW_IN_USE

Código de Erro: FLOW_IN_USE
Código de Status: 400

Descriçã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

EXISTING_USER

Código de Erro: EXISTING_USER
Código de Status: 400

Descriçã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

INVALID_APP_CONNECTION

Código de Erro: INVALID_APP_CONNECTION
Código de Status: 400

Descriçã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

INVALID_SAML_RESPONSE

Código de Erro: INVALID_SAML_RESPONSE
Código de Status: 400

Descriçã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

RATE_LIMITED

Código de Erro: RATE_LIMITED ou ratelimited
Código de Status: 429

Descriçã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