GenderAPI.io V2: σφάλματα, όρια και νέες προσπάθειες

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

Τα σφάλματα της εφαρμογής χρησιμοποιούν application/problem+json (RFC 9457). Βασίστε τη λογική σας στα σταθερά πεδία code και action, όχι στο κείμενο του detail που προορίζεται για ανθρώπους. Στα σφάλματα επικύρωσης, το errors περιέχει τους δείκτες JSON Pointer των πεδίων που επηρεάζονται. Αναφέρετε το 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 υπολογίζεται στα όρια αιτημάτων.