Erros e novas tentativas de API v2

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.

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

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.