Errori e tentativi API v2

Errori e codici di stato HTTP

Gli errori dell’applicazione usano application/problem+json (RFC 9457). Gestiscili tramite i campi stabili code e action, non tramite il testo di detail. Per gli errori di convalida, errors contiene i percorsi JSON Pointer dei campi interessati. Comunica request_id all’assistenza. Errori di connessione o del proxy possono produrre un corpo diverso: controlla Content-Type prima di interpretarlo come JSON.

Il seguente esempio sintetico 422 mostra una sintassi email non valida prima della fatturazione. Il catalogo pubblico degli errori elenca ogni codice, stato, spiegazione e azione suggerita.

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

Nuovi tentativi e fatturazione

Ogni richiesta di previsione è una nuova operazione, inclusa una richiesta identica inviata nuovamente. Ad ogni richiesta si applicano le normali regole di credito. Non esiste alcuna protezione dalle richieste duplicate, quindi evita i tentativi automatici dopo una perdita di connessione o un risultato sconosciuto.

Per una risposta 429, attendere Retry-After prima di inviare un'altra richiesta. Per errori di previsione, ispezionare prima code, action e meta.usage.billing_status. Per billing_reconciliation_required o fatturazione non confermata, contattare l'assistenza request_id prima di riprovare.

Un batch parzialmente riuscito può restituire HTTP 200. Controlla ogni articolo e invia nuovamente solo gli articoli non riusciti dopo la conferma della fatturazione; gli articoli riusciti verranno fatturati nuovamente se reinviati.

X-Request-ID e meta.request_id identificano il tentativo HTTP corrente. Leggi /usage per il saldo attuale. HEAD non avvia una previsione fatturabile. Le risposte alle previsioni e agli account non possono essere memorizzate nella cache.

I client devono tollerare campi di risposta aggiuntivi e preservare i valori null quando le informazioni non sono disponibili.

Limiti della richiesta

Gestisci HTTP 429 e Retry-After invece di dare per scontato che le richieste saranno sempre accettate a questi massimali. La capacità del servizio è condivisa. I valori visualizzati sono le impostazioni predefinite del servizio corrente. Le risposte al limite di velocità includono X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi Unix). Retry-After è un ritardo in secondi. Queste intestazioni descrivono i limiti delle richieste, non i crediti rimanenti. Anche la lettura gratuita di /usage conta ai fini dei limiti di velocità.