# Erros e novas tentativas de API v2

> Lidar com GenderAPI v2 Problem Details, erros de validação, limites de taxa e incerteza de faturamento. Entenda as cobranças por novas tentativas e quando entrar em contato com o suporte.

Canonical HTML: https://www.genderapi.io/pt/docs/v2/errors-and-retries

Last reviewed: 2026-09-25

## Erros e códigos de status HTTP

Erros de aplicativo usam application/problem+json (RFC 9457). Trate os erros usando os campos estáveis code e action, em vez do texto explicativo em detail. Para erros de validação, errors contém locais de ponteiro JSON para os campos afetados. Inclua request_id ao entrar em contato com o suporte. Falhas de proxy ou de conexão podem retornar um corpo de resposta diferente; verifique Content-Type antes de analisar JSON.

O exemplo sintético 422 a seguir mostra uma sintaxe de e-mail inválida antes do faturamento. O catálogo público de erros lista todos os códigos, status, explicações e ações sugeridas.

| Status HTTP | Significado típico | Próxima etapa |
| --- | --- | --- |
| 400 / 413 / 415 | JSON malformado, corpo superdimensionado ou tipo de mídia não compatível. | Corrija a solicitação. |
| 401 / 403 | Acesso rejeitado, restrição de conta ou créditos insuficientes. | Inspecione code; corrija o acesso ou reabasteça os créditos / aguarde a redefinição do teste. |
| 422 | Entrada inválida ou opções incompatíveis. | Corrija os campos identificados em errors. |
| 404 / 405 | Rota desconhecida ou método HTTP não suportado. | Verifique o caminho do endpoint e o cabeçalho de resposta Allow. |
| 429 | Taxa ou limite de simultaneidade. | Aguarde Retry-After antes de enviar outra solicitação. |
| 500 | Falha inesperada no servidor. | Entre em contato com o suporte com request_id; verifique o faturamento antes de tentar novamente. |
| 502 / 503 / 504 | Falha de provedor, dependência, faturamento ou tempo limite. | Inspecione code, action e billing_status antes de tentar novamente. |

```json
{
  "type": "urn:genderapi:problem:validation_error",
  "title": "validation error",
  "status": 422,
  "detail": "A valid email address is required.",
  "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
  "code": "validation_error",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "documentation": "https://api.genderapi.io/api/v2/errors",
  "action": "correct_request",
  "errors": [
    {
      "pointer": "/value",
      "message": "Invalid email address."
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 0,
      "remaining_credits": null,
      "billing_status": "not_charged",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [Catálogo completo de erros v2](https://api.genderapi.io/api/v2/errors)

## Novas tentativas e cobrança

Cada solicitação de previsão é uma nova operação, incluindo uma solicitação idêntica enviada novamente. As regras normais de crédito se aplicam a cada solicitação. Não há proteção contra solicitações duplicadas; portanto, evite novas tentativas automáticas após uma perda de conexão ou um resultado desconhecido.

Para uma resposta 429, aguarde Retry-After antes de enviar outra solicitação. Para falhas de previsão, inspecione primeiro code, action e meta.usage.billing_status. Para billing_reconciliation_required ou faturamento não confirmado, entre em contato com o suporte com request_id antes de tentar novamente.

Um lote parcialmente bem-sucedido pode retornar HTTP 200. Verifique cada item e reenvie apenas os itens com falha após a confirmação do faturamento; os itens bem-sucedidos seriam cobrados novamente se reenviados.

X-Request-ID e meta.request_id identificam a tentativa HTTP atual. Leia /usage para o saldo atual. HEAD não inicia uma previsão faturável. As previsões e as respostas da conta não podem ser armazenadas em cache.

Os clientes devem tolerar campos de resposta aditivos e preservar os valores null quando as informações não estiverem disponíveis.

## Limites de solicitação

Lide com HTTP 429 e Retry-After em vez de presumir que as solicitações sempre serão aceitas nesses limites. A capacidade de serviço é compartilhada. Os valores mostrados são os padrões atuais do serviço. As respostas de limite de taxa incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos Unix). Retry-After é um atraso em segundos. Esses cabeçalhos descrevem os limites de solicitação, não os créditos restantes. Até mesmo a leitura gratuita do /usage conta para os limites de taxa.

| Limite | Valor |
| --- | --- |
| Corpo da solicitação JSON | 64 KiB máximo |
| Valor de previsão | 1–254 caracteres |
| Lote | 50 itens com chave API; 10 com o teste IP |
| Taxa da conta | 120 solicitações por minuto |
| Taxa IP | 600 solicitações por minuto |
| Operações simultâneas | 2 por conta; 16 em todo o serviço |