Pular para o conteúdo principal

​
Tratamento de erros

A API usa códigos HTTP padrão. Todos os erros retornam JSON: 
{
  "statusCode": 400,
  "message": "Descrição do erro",
  "error": "Bad Request"
}

​
Códigos de erro

CódigoNomeQuando ocorre
400Bad RequestParâmetros inválidos ou ausentes
401UnauthorizedAPI key ausente ou inválida
402Payment RequiredSaldo insuficiente para emissão
403ForbiddenPlano insuficiente para o endpoint
404Not FoundRecurso não encontrado
422Unprocessable EntityDados válidos mas não processáveis
429Too Many RequestsRate limit atingido
500Internal Server ErrorErro interno — contate o suporte

​
Exemplos de resposta

​
401 — API Key inválida

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

​
403 — Plano insuficiente

{
  "statusCode": 403,
  "message": "This endpoint requires an Advanced tier API key",
  "error": "Forbidden"
}

​
429 — Rate limit

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}
O header Retry-After indica quantos segundos aguardar antes de tentar novamente.

​
Boas práticas

  • Sempre verifique o statusCode antes de processar a resposta
  • Implemente retry com backoff exponencial para erros 429 e 500
  • Registre o body completo do erro para facilitar debugging
  • Para 401, verifique se a API key não foi revogada em Configurações → Integrações

​
Exemplo de retry com backoff

async function apiCall(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('Retry-After') || '5');
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    return res;
  }
  throw new Error('Rate limit exceeded after retries');
}