GenderAPI.io V2 : erreurs, limites et nouvelles tentatives

Erreurs et codes d'état HTTP

Les erreurs applicatives utilisent application/problem+json (RFC 9457). Basez votre traitement sur les champs stables code et action, et non sur le texte lisible de detail. Pour les erreurs de validation, errors contient les emplacements JSON Pointer des champs concernés. Indiquez request_id lorsque vous contactez l'assistance. Les défaillances de proxy ou de transport peuvent renvoyer un autre corps ; vérifiez Content-Type avant d'analyser le JSON.

L'exemple synthétique 422 ci-dessous montre une syntaxe d'adresse e-mail non valide détectée avant facturation. Le catalogue public des erreurs répertorie chaque code, statut, explication et action suggérée.

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

• Catalogue complet des erreurs V2

Champs de la réponse d'erreur

Accès, facturation et métadonnées de la requête

Nouvelles tentatives et facturation

Chaque requête de prédiction est une nouvelle opération, y compris une requête identique renvoyée. Les règles de crédit habituelles s'appliquent à chaque requête. Il n'existe aucune protection contre les requêtes en double ; évitez donc les nouvelles tentatives automatiques après une perte de connexion ou une issue incertaine.

Pour une réponse 429, attendez le délai indiqué par Retry-After avant d'envoyer une autre requête. En cas d'échec de prédiction, examinez d'abord code, action et meta.usage.billing_status. Pour billing_reconciliation_required ou une facturation unconfirmed, contactez l'assistance avec request_id avant de réessayer.

Un lot partiellement réussi peut renvoyer HTTP 200. Vérifiez chaque élément et ne soumettez de nouveau que les éléments échoués une fois la facturation confirmée ; les éléments réussis seraient facturés une seconde fois.

X-Request-ID et meta.request_id identifient la tentative HTTP en cours. Consultez /usage pour connaître le solde actuel. HEAD ne déclenche aucune prédiction facturable. Les réponses de prédiction et de compte ne peuvent pas être mises en cache.

Les clients doivent tolérer l'ajout de nouveaux champs de réponse et conserver les valeurs null lorsque l'information n'est pas disponible.

Limites de requêtes

Gérez HTTP 429 et Retry-After au lieu de supposer que les requêtes seront toujours acceptées jusqu'à ces plafonds. La capacité du service est partagée. Les valeurs indiquées sont les valeurs par défaut actuelles du service. Les réponses de limitation incluent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes Unix). Retry-After est un délai en secondes. Ces en-têtes décrivent les limites de requêtes, et non les crédits restants. Même la consultation gratuite de /usage est prise en compte dans les limites de débit.