Codigos de Erro

Conceituacao

A Ogmma API utiliza codigos de erro padronizados para indicar o tipo de problema ocorrido em uma requisicao. Cada erro retorna um codigo unico, um status HTTP correspondente e uma mensagem descritiva que facilita a identificacao e tratamento do problema.

Formato padrao de erro

Erros de aplicacao (AppError)

A maioria dos erros retorna o seguinte formato:

{
  "message": "Canal nao encontrado",
  "code": "CHANNEL_NOT_FOUND",
  "details": {
    "channelId": "abc123"
  }
}

Campo	Tipo	Descricao
message	string	Mensagem descritiva em portugues (pode variar, nao use para tratamento programatico)
code	string	Codigo unico do erro (constante, use para tratamento programatico)
details	object	Informacoes adicionais sobre o erro (opcional, varia por tipo de erro)

Erros de validacao (ZodError)

Quando os dados de entrada sao invalidos, o formato inclui um array de erros detalhados:

{
  "message": "O numero do destinatario e obrigatorio",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "path": "to",
      "message": "Required",
      "validation": "invalid_type"
    }
  ]
}

Campo	Tipo	Descricao
message	string	Mensagem do primeiro erro de validacao
code	string	Sempre VALIDATION_ERROR
errors	array	Lista detalhada de todos os erros de validacao
errors[].path	string	Caminho do campo com erro (ex: to, content.text)
errors[].message	string	Mensagem descritiva do erro
errors[].validation	string	Tipo de validacao que falhou

Erros internos (500)

Erros inesperados retornam formato aninhado:

{
  "error": {
    "message": "Erro interno do servidor",
    "code": "INTERNAL_SERVER_ERROR"
  }
}

Tabela de codigos

Autenticacao e Autorizacao

Codigo	HTTP Status	Descricao	Exemplo
AUTHENTICATION_REQUIRED	401	Requisicao sem token de autenticacao ou com token ausente	Header Authorization nao enviado
UNAUTHORIZED	401	Token ou API Key invalido	Credenciais incorretas ou expiradas
INVALID_API_KEY	401	API key invalida, expirada ou revogada	Chave oapi_sk_live_... nao reconhecida
INVALID_TOKEN	401	Token JWT invalido, expirado ou malformado	Token JWT com assinatura invalida
FORBIDDEN_PERMISSION	403	O usuario ou API key nao possui permissao para a operacao	Chave sem permissao messages.send tentando enviar mensagem

Rate Limiting

Codigo	HTTP Status	Descricao	Exemplo
RATE_LIMIT_EXCEEDED	429	Limite de requisicoes por minuto excedido	Mais de 60 requisicoes/min com limite de 60

Canais

Codigo	HTTP Status	Descricao	Exemplo
CHANNEL_NOT_FOUND	404	Canal nao encontrado na instituicao	channelId inexistente ou de outra instituicao
CHANNEL_NOT_CONNECTED	400	Canal existe mas nao esta conectado	Tentativa de enviar mensagem por canal DISCONNECTED
CHANNEL_NOT_WABA	400	Canal nao e do tipo WABA	Tentativa de enviar template por canal Baileys

Conversas

Codigo	HTTP Status	Descricao	Exemplo
CONVERSATION_NOT_FOUND	404	Conversa nao encontrada	conversationId inexistente ou de outra instituicao

Contatos

Codigo	HTTP Status	Descricao	Exemplo
CONTACT_NOT_FOUND	404	Contato nao encontrado	contactId inexistente ou de outra instituicao

Mensagens

Codigo	HTTP Status	Descricao	Exemplo
MESSAGE_NOT_FOUND	404	Mensagem nao encontrada	messageId inexistente ou de outra instituicao
INVALID_PHONE_NUMBER	400	Numero de telefone em formato invalido	Numero sem codigo de pais ou com caracteres invalidos
NUMBER_NOT_ON_WHATSAPP	400	O numero informado nao possui conta WhatsApp	Numero fixo ou celular sem WhatsApp

Midia

Codigo	HTTP Status	Descricao	Exemplo
MEDIA_TOO_LARGE	400	Arquivo de midia excede o tamanho maximo permitido	Imagem acima de 16MB ou video acima de 64MB
PAYLOAD_TOO_LARGE	413	O conteudo enviado excede o limite maximo	Payload acima de 50MB
UNSUPPORTED_MEDIA_TYPE	415	Tipo de midia nao suportado	Arquivo .exe ou formato nao reconhecido

Envio em Massa

Codigo	HTTP Status	Descricao	Exemplo
BULK_BATCH_LIMIT_REACHED	400	Limite de batches ativos atingido	Mais de 3 batches em execucao simultaneamente
BULK_BATCH_NOT_FOUND	404	Batch nao encontrado	batchId inexistente ou de outra instituicao
BULK_BATCH_NOT_CANCELLABLE	400	Batch nao pode ser cancelado	Batch ja concluido ou ja cancelado
BULK_CANCEL_FAILED	400	Falha ao cancelar o batch	Erro ao marcar batch como cancelado

Templates

Codigo	HTTP Status	Descricao	Exemplo
TEMPLATE_NOT_FOUND	404	Template nao encontrado	Nome do template inexistente na conta WABA
TEMPLATE_NOT_APPROVED	400	Template existe mas nao foi aprovado pelo Meta	Template com status REJECTED ou PENDING

Webhooks

Codigo	HTTP Status	Descricao	Exemplo
WEBHOOK_URL_UNREACHABLE	400	URL do webhook nao pode ser alcancada	URL retorna timeout ou erro de conexao na validacao

Sandbox

Codigo	HTTP Status	Descricao	Exemplo
SANDBOX_ONLY	400	Endpoint disponivel apenas no ambiente sandbox	Chamar /sandbox/test com chave live
CHANNEL_DISCONNECTED	400	Canal desconectado (cenario simulado)	Header X-Ogmma-Sandbox-Scenario: channel_disconnected
SEND_TIMEOUT	408	Timeout no envio da mensagem (cenario simulado)	Header X-Ogmma-Sandbox-Scenario: timeout

Validacao e Erros Gerais

Codigo	HTTP Status	Descricao	Exemplo
VALIDATION_ERROR	400	Dados de entrada invalidos	Campo obrigatorio ausente, tipo incorreto, valor fora do range
INTERNAL_SERVER_ERROR	500	Erro interno do servidor	Falha inesperada no processamento da requisicao

Headers de Rate Limit

Todas as respostas da API incluem headers que informam o estado atual do seu limite de requisicoes:

Header	Descricao
X-RateLimit-Limit	Numero maximo de requisicoes permitidas por minuto
X-RateLimit-Remaining	Numero de requisicoes restantes na janela atual
X-RateLimit-Reset	Timestamp (Unix epoch em segundos) de quando a janela de rate limit sera reiniciada
Retry-After	Numero de segundos para aguardar antes de fazer uma nova requisicao (presente apenas em respostas 429)

Exemplo de headers em uma resposta normal

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1705312860

Exemplo de resposta com rate limit excedido

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312860
Retry-After: 45

{
  "message": "Limite de requisicoes excedido. Tente novamente em 45 segundos.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Tratamento de erros recomendado

Erros retentaveis

Os seguintes erros podem ser resolvidos com uma nova tentativa apos um intervalo:

Codigo	Estrategia
RATE_LIMIT_EXCEEDED	Aguarde o tempo indicado no header Retry-After
INTERNAL_SERVER_ERROR	Tente novamente com backoff exponencial (1s, 2s, 4s, 8s)
CHANNEL_NOT_CONNECTED	Verifique o status do canal e tente novamente apos reconexao

Erros nao retentaveis

Os seguintes erros indicam problemas que precisam ser corrigidos antes de uma nova tentativa:

Codigo	Acao necessaria
AUTHENTICATION_REQUIRED	Verifique o header Authorization
INVALID_API_KEY	Use uma chave valida ou crie uma nova
FORBIDDEN_PERMISSION	Atualize as permissoes da chave
VALIDATION_ERROR	Corrija os dados de entrada conforme o campo errors
NUMBER_NOT_ON_WHATSAPP	O destinatario nao possui WhatsApp
TEMPLATE_NOT_APPROVED	Aguarde a aprovacao do template pelo Meta

Dica

Sempre trate os erros pelo campo code (ex: CHANNEL_NOT_FOUND) e nao pelo campo message, pois a mensagem pode variar entre versoes da API. O codigo e estavel e garantido pela API.