Erros e novas tentativas na API V2

Erros e códigos de status HTTP

Erros da aplicação usam application/problem+json (RFC 9457). Baseie a lógica nos campos estáveis code e action, não no texto legível de detail. Erros de validação incluem em errors a localização em JSON Pointer. Informe o request_id ao entrar em contato com o suporte. Falhas de proxy ou de transporte podem retornar um corpo diferente; por isso, verifique Content-Type antes de interpretar o JSON.

O exemplo sintético 422 a seguir mostra uma sintaxe de e-mail inválida antes da cobrança. O catálogo público de erros lista cada código, status, explicação e ação sugerida.

{
  "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 da V2

Campos da resposta de erro

Metadados de acesso, cobrança e requisição

Novas tentativas e cobrança

Cada requisição de previsão é uma nova operação, inclusive uma requisição idêntica enviada novamente. As regras normais de créditos se aplicam a cada requisição. Não há proteção contra requisições duplicadas; por isso, evite novas tentativas automáticas após uma perda de conexão ou quando o resultado da operação for desconhecido.

Em uma resposta 429, aguarde o tempo de Retry-After antes de enviar outra requisição. Em falhas de previsão, verifique primeiro code, action e meta.usage.billing_status. Em caso de billing_reconciliation_required ou de cobrança não confirmada, entre em contato com o suporte informando o request_id antes de fazer uma nova tentativa.

Um lote parcialmente bem-sucedido pode retornar HTTP 200. Verifique cada item e reenvie apenas os itens com falha depois que a cobrança for confirmada; itens bem-sucedidos seriam cobrados novamente se fossem reenviados.

X-Request-ID e meta.request_id identificam a tentativa HTTP atual. Consulte /usage para ver o saldo atual. HEAD não inicia uma previsão cobrada. Respostas de previsão e de conta não podem ser armazenadas em cache.

Os clientes devem tolerar novos campos adicionados à resposta e preservar valores null quando a informação não estiver disponível.

Limites de requisições

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