Erreurs et tentatives API v2

Erreurs et codes d'état HTTP

Les erreurs d'application utilisent application/problem+json (RFC 9457). Gérez les erreurs à l'aide des champs stables code et action, plutôt que du texte explicatif dans detail. Pour les erreurs de validation, errors contient les emplacements du pointeur JSON pour les champs concernés. Incluez request_id lorsque vous contactez l’assistance. Les échecs de proxy ou de connexion peuvent renvoyer un corps de réponse différent ; vérifiez Content-Type avant d’analyser JSON.

L'exemple synthétique 422 suivant montre une syntaxe de courrier électronique non valide avant la facturation. Le catalogue d'erreurs public répertorie tous les codes, statuts, explications et actions suggérées.

{
  "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 d'erreurs v2

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 normales de crédit s'appliquent à chaque demande. Il n'y a pas de protection contre les demandes en double, évitez donc les tentatives automatiques après une perte de connexion ou un résultat inconnu.

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

Un lot partiellement réussi peut renvoyer 200 HTTP. Vérifiez chaque élément et soumettez à nouveau uniquement les éléments ayant échoué une fois la facturation confirmée ; les éléments réussis seront à nouveau facturés s'ils sont soumis à nouveau.

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

Les clients doivent tolérer les champs de réponse additifs et conserver les valeurs null lorsque les informations ne sont pas disponibles.

Limites de requête

Gérez HTTP 429 et Retry-After plutôt que de supposer que les demandes seront toujours acceptées à ces plafonds. La capacité de service est partagée. Les valeurs affichées sont les valeurs par défaut actuelles du service. Les réponses de limite de débit 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 des demandes, et non les crédits restants. Même la lecture gratuite /usage compte dans les limites de débit.