Tratamento de erros

A API da Meirra usa os códigos de status HTTP convencionais para indicar sucesso ou falha das requisições. Em geral: • **2xx** — Sucesso. A requisição funcionou como esperado. • **4xx** — Erro do cliente. A requisição é inválida ou não pode ser atendida. • **5xx** — Erro do servidor. Algo deu errado do nosso lado. Todas as respostas de erro seguem uma estrutura JSON consistente com código, mensagem e detalhes úteis para diagnosticar e tratar o problema.

Todos os erros seguem um formato consistente: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Descrição legível do erro", "details": { ... } } } ``` O campo `code` é um código legível por máquina que você pode usar na sua lógica de tratamento de erros. O `message` traz uma descrição legível por humanos. O objeto opcional `details` adiciona contexto específico ao tipo de erro.

Erros de autenticação ocorrem quando sua chave de API está faltando, é inválida ou não tem permissão. | Código | HTTP | Descrição | |--------|------|-----------| | `INVALID_API_KEY` | 401 | Chave de API faltando ou inválida | | `API_KEY_REVOKED` | 401 | Chave de API foi revogada | | `IP_NOT_ALLOWED` | 403 | IP da requisição fora da lista permitida | **Exemplo:** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "A chave de API fornecida é inválida ou está faltando" } } ``` **Como resolver:** Confirme que sua chave de API está correta e incluída no cabeçalho `x-api-key`. Verifique no Painel do Desenvolvedor se a chave foi revogada.

Erros de saldo ocorrem quando sua conta não tem créditos suficientes para a requisição. | Código | HTTP | Descrição | |--------|------|-----------| | `INSUFFICIENT_BALANCE` | 402 | Saldo insuficiente para a requisição | **Exemplo:** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Seu saldo de $0.50 é insuficiente para esta requisição ($1.00 necessário)", "details": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **Como resolver:** Recarregue o saldo da sua conta no Painel do Desenvolvedor. Considere configurar alertas de saldo baixo para evitar interrupções.

Erros de limite de taxa ocorrem quando você excede a frequência de requisições permitida. | Código | HTTP | Descrição | |--------|------|-----------| | `RATE_LIMIT_EXCEEDED` | 429 | Requisições em excesso | **Exemplo:** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Limite de taxa excedido. Tente novamente em 60 segundos.", "details": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **Como resolver:** Implemente backoff exponencial. Use o cabeçalho `Retry-After` para saber quando tentar de novo. Distribua as requisições ao longo do tempo.

Erros de validação ocorrem quando os parâmetros da requisição estão faltando ou são inválidos. | Código | HTTP | Descrição | |--------|------|-----------| | `INVALID_REQUEST` | 400 | Parâmetros faltando ou inválidos | | `INVALID_EMAIL` | 400 | Formato de e-mail inválido | | `BATCH_TOO_LARGE` | 400 | Lote excede o tamanho máximo | **Exemplo:** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Falha na validação da requisição", "details": { "field": "email", "issue": "E-mail é obrigatório" } } } ``` **Como resolver:** Verifique o campo `details` para identificar o erro de validação específico. Garanta que todos os campos obrigatórios estejam presentes no formato esperado.

Erros de serviço ocorrem quando algo dá errado na nossa infraestrutura. | Código | HTTP | Descrição | |--------|------|-----------| | `SERVICE_ERROR` | 500 | Falha interna do serviço | | `SERVICE_UNAVAILABLE` | 503 | Serviço temporariamente indisponível | | `UPSTREAM_ERROR` | 502 | Dependência externa falhou | **Exemplo:** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "Ocorreu um erro interno. Tente novamente mais tarde." } } ``` **Como resolver:** Estes são erros transitórios. Implemente lógica de retry com backoff exponencial. Se os erros persistirem, consulte a página de status ou fale com o suporte.