Skip to main content
A Oxenty API usa códigos HTTP padrão para indicar sucesso ou falha das requisições. Erros incluem informações detalhadas para facilitar a depuração.

Estrutura de Erro

Todas as respostas de erro seguem o mesmo formato:
{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "O campo 'phone' é obrigatório",
  "details": {
    "field": "phone",
    "constraint": "required"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/messages/send"
}
CampoTipoDescrição
statusCodenumberCódigo HTTP do erro
errorstringCódigo identificador do erro
messagestringMensagem legível descrevendo o erro
detailsobjectInformações adicionais (opcional)
timestampstringData/hora do erro (ISO 8601)
pathstringEndpoint que gerou o erro

Códigos HTTP

CódigoSignificado
200OK - Requisição bem sucedida
201Created - Recurso criado com sucesso
204No Content - Sucesso sem corpo de resposta

Códigos de Erro

Autenticação

CódigoHTTPDescrição
UNAUTHORIZED401API Key ausente ou inválida
API_KEY_REVOKED403API Key foi revogada
INSUFFICIENT_PERMISSIONS403Sem permissão para o recurso

Validação

CódigoHTTPDescrição
VALIDATION_ERROR400Dados de entrada inválidos
INVALID_PHONE_FORMAT400Formato de telefone inválido
INVALID_JID_FORMAT400Formato de JID inválido
MISSING_REQUIRED_FIELD400Campo obrigatório ausente

Sessões

CódigoHTTPDescrição
SESSION_NOT_FOUND404Sessão não existe
SESSION_ALREADY_EXISTS409Sessão com mesmo nome já existe
SESSION_NOT_CONNECTED400Sessão não está conectada
SESSION_LIMIT_REACHED403Limite de sessões do plano atingido
SESSION_CREATION_FAILED500Falha ao criar sessão

Mensagens

CódigoHTTPDescrição
MESSAGE_SEND_FAILED500Falha ao enviar mensagem
MESSAGE_LIMIT_REACHED403Limite de mensagens do plano atingido
RECIPIENT_NOT_ON_WHATSAPP400Destinatário não usa WhatsApp
MEDIA_TOO_LARGE400Arquivo excede o limite de tamanho
UNSUPPORTED_MEDIA_TYPE400Tipo de mídia não suportado

Grupos

CódigoHTTPDescrição
GROUP_NOT_FOUND404Grupo não existe
NOT_GROUP_ADMIN403Não é administrador do grupo
PARTICIPANT_ALREADY_EXISTS409Participante já está no grupo
PARTICIPANT_NOT_FOUND404Participante não encontrado

Contatos

CódigoHTTPDescrição
CONTACT_NOT_FOUND404Contato não encontrado
NUMBER_NOT_ON_WHATSAPP400Número não está no WhatsApp

Rate Limiting

CódigoHTTPDescrição
TOO_MANY_REQUESTS429Rate limit excedido
WHATSAPP_RATE_LIMIT429Rate limit do WhatsApp

Webhooks

CódigoHTTPDescrição
WEBHOOK_NOT_FOUND404Webhook não encontrado
WEBHOOK_URL_UNREACHABLE400URL do webhook não acessível
WEBHOOK_LIMIT_REACHED403Limite de webhooks do plano

Tratamento de Erros

Exemplo em TypeScript

import { OxentyClient, OxentyError } from 'oxenty-sdk';

const client = new OxentyClient({
  baseUrl: 'https://api.oxenty.api.br',
  apiKey: process.env.OXENTY_API_KEY,
});

async function sendMessage() {
  try {
    const result = await client.messages.sendText(sessionId, {
      to: '5511999999999',
      text: 'Olá!',
    });
    return result;
  } catch (error) {
    if (error instanceof OxentyError) {
      switch (error.code) {
        case 'SESSION_NOT_CONNECTED':
          // Reconectar sessão
          await client.sessions.connect(sessionId);
          break;
          
        case 'RECIPIENT_NOT_ON_WHATSAPP':
          // Notificar usuário
          console.log('Destinatário não usa WhatsApp');
          break;
          
        case 'TOO_MANY_REQUESTS':
          // Aguardar e tentar novamente
          await sleep(error.retryAfter * 1000);
          return sendMessage();
          
        case 'MESSAGE_LIMIT_REACHED':
          // Upgrade de plano necessário
          console.log('Limite de mensagens atingido');
          break;
          
        default:
          console.error(`Erro: ${error.message}`);
      }
    }
    throw error;
  }
}

Exemplo em Python

import os
import time
import requests

API_KEY = os.environ.get('OXENTY_API_KEY')
BASE_URL = 'https://api.oxenty.api.br'

def send_message():
    try:
    response = requests.post(
      f"{BASE_URL}/api/messages/send-text",
      headers={
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
      },
      json={
        'sessionId': session_id,
        'to': '5511999999999',
        'text': 'Olá!'
      },
      timeout=30,
    )

    if response.status_code == 429:
      time.sleep(2)
      return send_message()

    response.raise_for_status()
    return response.json()
  except requests.HTTPError as err:
    try:
      payload = err.response.json()
      print(f"Erro: {payload.get('error')} - {payload.get('message')}")
    except Exception:
      print(f"Erro HTTP: {err}")
    raise

Boas Práticas

Não use apenas catch genérico. Trate cada tipo de erro de forma adequada para melhor experiência do usuário.
Para erros 5xx e 429, implemente retry automático com exponential backoff.
Salve logs detalhados de erros incluindo timestamp, path, e details para facilitar troubleshooting.
Configure alertas quando a taxa de erros 4xx ou 5xx ultrapassar um threshold.

Suporte

Se você encontrar um erro que não consegue resolver: