Tratamento de Erros

A API retorna respostas padronizadas para facilitar o tratamento de erros. Todos os erros incluem um código único e mensagem descritiva.

Formato da Resposta de Erro

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'email' é obrigatório",
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

Códigos HTTP

2xx - Sucesso

A requisição foi processada com sucesso.

200 - OK (GET, PATCH)
201 - Created (POST)
204 - No Content (DELETE)

4xx - Erro do Cliente

Há um problema com a requisição enviada.

400 - Bad Request (dados inválidos)
401 - Unauthorized (API Key inválida)
403 - Forbidden (sem permissão)
404 - Not Found (recurso não existe)
409 - Conflict (recurso já existe)
422 - Unprocessable Entity (validação falhou)
429 - Too Many Requests (rate limit)

5xx - Erro do Servidor

Erro interno no servidor. Tente novamente.

500 - Internal Server Error
502 - Bad Gateway
503 - Service Unavailable

Códigos de Erro Comuns

HTTP	Codigo	Descricao	Acao
400	`VALIDATION_ERROR`	Dados inválidos no body	Verifique os campos enviados
400	`INVALID_JSON`	JSON malformado	Verifique a sintaxe do JSON
401	`UNAUTHORIZED`	API Key não fornecida ou inválida	Verifique o header Authorization
401	`API_KEY_EXPIRED`	API Key expirada	Crie uma nova API Key
403	`FORBIDDEN`	Sem permissão para esta operação	Verifique os escopos da API Key
403	`SCOPE_REQUIRED`	Escopo específico necessário	Adicione o escopo à API Key
404	`NOT_FOUND`	Recurso não encontrado	Verifique o ID/externalId
409	`CONFLICT`	Recurso já existe	Use update ou outro externalId
409	`DUPLICATE_ENTRY`	Entrada duplicada	O registro já existe
422	`UNPROCESSABLE_ENTITY`	Entidade não processável	Dados válidos mas não podem ser processados
429	`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido	Aguarde o tempo indicado em Retry-After
500	`INTERNAL_ERROR`	Erro interno do servidor	Tente novamente ou contate suporte

Erros de Validação

Quando há erros de validação (400/422), o campo detailscontém informações específicas sobre cada campo:

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "email",
          "message": "Email inválido",
          "code": "invalid_email"
        },
        {
          "field": "phone",
          "message": "Formato de telefone inválido",
          "code": "invalid_format"
        }
      ]
    }
  }
}

Estratégia de Retry

Recomendamos implementar retry com backoff exponencial para erros recuperáveis:

Código	Retry?	Ação
`400`	❌ Não	Corrija os dados e reenvie
`401`	❌ Não	Verifique a API Key
`403`	❌ Não	Verifique permissões
`404`	❌ Não	Verifique o ID
`429`	✅ Sim	Aguarde Retry-After
`500`	✅ Sim	Retry com backoff
`502/503`	✅ Sim	Retry com backoff

Exemplo de Implementação

JavaScript

async function apiRequest(url, options, maxRetries = 3) {
  let lastError;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      // Sucesso
      if (response.ok) {
        return await response.json();
      }
      
      // Erro não recuperável
      if ([400, 401, 403, 404].includes(response.status)) {
        const error = await response.json();
        throw new Error(error.error?.message || 'Request failed');
      }
      
      // Rate limit - aguarda tempo indicado
      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        await sleep(retryAfter * 1000);
        continue;
      }
      
      // Erro do servidor - retry com backoff
      if (response.status >= 500) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await sleep(delay);
        continue;
      }
      
    } catch (error) {
      lastError = error;
      
      // Erro de rede - retry
      if (error.name === 'TypeError') {
        const delay = Math.pow(2, attempt) * 1000;
        await sleep(delay);
        continue;
      }
      
      throw error;
    }
  }
  
  throw lastError || new Error('Max retries exceeded');
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}