Σφάλματα API v2 και επαναλήψεις

Σφάλματα και κωδικοί κατάστασης HTTP

Τα σφάλματα εφαρμογής χρησιμοποιούν application/problem+json (RFC 9457). Χειριστείτε τα σφάλματα χρησιμοποιώντας τα σταθερά πεδία code και action, αντί για το επεξηγηματικό κείμενο στο detail. Για σφάλματα επικύρωσης, το errors περιέχει θέσεις δείκτη JSON για τα επηρεαζόμενα πεδία. Συμπεριλάβετε το request_id όταν επικοινωνείτε με την υποστήριξη. Οι αποτυχίες διακομιστή μεσολάβησης ή σύνδεσης ενδέχεται να επιστρέψουν διαφορετικό σώμα απόκρισης. ελέγξτε το Content-Type πριν αναλύσετε το JSON.

Το ακόλουθο συνθετικό παράδειγμα 422 δείχνει μη έγκυρη σύνταξη email πριν από τη χρέωση. Ο δημόσιος κατάλογος σφαλμάτων παραθέτει κάθε κωδικό, κατάσταση, επεξήγηση και προτεινόμενη ενέργεια.

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

• Πλήρης κατάλογος σφαλμάτων v2

Επαναλήψεις και χρέωση

Κάθε αίτημα πρόβλεψης είναι μια νέα λειτουργία, συμπεριλαμβανομένου ενός πανομοιότυπου αιτήματος που αποστέλλεται ξανά. Για κάθε αίτημα ισχύουν οι συνήθεις κανόνες πίστωσης. Δεν υπάρχει προστασία διπλών αιτημάτων, επομένως αποφύγετε τις αυτόματες επαναλήψεις μετά από απώλεια σύνδεσης ή άγνωστο αποτέλεσμα.

Για απάντηση 429, περιμένετε το Retry-After πριν στείλετε άλλο αίτημα. Για αποτυχίες πρόβλεψης, επιθεωρήστε πρώτα τα code, action και meta.usage.billing_status. Για billing_reconciliation_required ή μη επιβεβαιωμένη χρέωση, επικοινωνήστε με την υποστήριξη με το request_id πριν δοκιμάσετε ξανά.

Μια μερικώς επιτυχημένη παρτίδα μπορεί να επιστρέψει το HTTP 200. Ελέγξτε κάθε είδος και υποβάλετε ξανά μόνο αποτυχημένα στοιχεία αφού επιβεβαιωθεί η χρέωση. Τα επιτυχημένα στοιχεία θα χρεωθούν ξανά εάν υποβληθούν εκ νέου.

Τα X-Request-ID και meta.request_id προσδιορίζουν την τρέχουσα προσπάθεια HTTP. Διαβάστε το /usage για το τρέχον υπόλοιπο. Το HEAD δεν ξεκινά μια χρεώσιμη πρόβλεψη. Οι αποκρίσεις πρόβλεψης και λογαριασμού δεν είναι προσωρινά αποθηκευμένες.

Οι πελάτες θα πρέπει να ανέχονται πεδία πρόσθετης απόκρισης και να διατηρούν τις τιμές null όταν οι πληροφορίες δεν είναι διαθέσιμες.

Όρια αιτημάτων

Χειριστείτε τα HTTP 429 και Retry-After αντί να υποθέσετε ότι τα αιτήματα θα γίνονται πάντα δεκτά σε αυτά τα ανώτατα όρια. Η χωρητικότητα εξυπηρέτησης είναι κοινή. Οι τιμές που εμφανίζονται είναι οι τρέχουσες προεπιλογές υπηρεσίας. Οι αποκρίσεις ορίου ρυθμού περιλαμβάνουν X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset (δευτερόλεπτα Unix). Το Retry-After είναι μια καθυστέρηση σε δευτερόλεπτα. Αυτές οι κεφαλίδες περιγράφουν τα όρια αιτημάτων, όχι τις υπόλοιπες πιστώσεις. Ακόμη και η δωρεάν ανάγνωση /usage μετράει στα όρια τιμών.