GenderAPI.io V2: errori, limiti e nuovi tentativi

Errori e codici di stato HTTP

Gli errori dell'applicazione usano application/problem+json (RFC 9457). Basa la logica sui campi stabili code e action, non sul testo leggibile di detail. Negli errori di convalida, errors contiene i JSON Pointer dei campi interessati. Indica request_id quando contatti l'assistenza. In caso di errori del proxy o di trasmissione il corpo della risposta può essere diverso: controlla Content-Type prima di analizzare il JSON.

Il seguente esempio sintetico 422 mostra una sintassi email non valida, rilevata prima dell'addebito. Il catalogo pubblico degli errori elenca tutti i codici, gli stati, le spiegazioni e le azioni consigliate.

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

• Catalogo completo degli errori V2

Campi della risposta di errore

Metadati di accesso, addebito e richiesta

Nuovi tentativi e addebiti

Ogni richiesta di previsione è una nuova operazione, anche quando si reinvia una richiesta identica. A ogni richiesta si applicano le normali regole sui crediti. Non esiste una protezione contro le richieste duplicate: evita quindi i nuovi tentativi automatici dopo un'interruzione della connessione o un esito sconosciuto.

In caso di risposta 429, attendi il tempo indicato in Retry-After prima di inviare un'altra richiesta. In caso di previsioni non riuscite, controlla prima code, action e meta.usage.billing_status. In caso di billing_reconciliation_required o di addebito non confermato, contatta l'assistenza indicando request_id prima di riprovare.

Un batch riuscito solo in parte può restituire HTTP 200. Controlla ogni elemento e, dopo la conferma dell'addebito, invia di nuovo solo gli elementi non riusciti; gli elementi riusciti verrebbero addebitati un'altra volta.

X-Request-ID e meta.request_id identificano il tentativo HTTP corrente. Leggi il saldo attuale tramite /usage. HEAD non avvia una previsione a pagamento. Le risposte di previsione e dell'account non sono memorizzabili nella cache.

I client devono tollerare nuovi campi aggiunti alla risposta e conservare i valori null quando un'informazione non è disponibile.

Limiti delle richieste

Gestisci HTTP 429 e Retry-After invece di presumere che le richieste vengano sempre accettate fino a questi valori massimi. La capacità del servizio è condivisa. I valori indicati sono le impostazioni predefinite attuali del servizio. Le risposte di limitazione includono X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi Unix). Retry-After è un'attesa in secondi. Queste intestazioni descrivono i limiti delle richieste, non i crediti residui. Anche la lettura gratuita di /usage rientra nei limiti delle richieste.