API v2 -virheet ja uudelleenyritykset

Virheet ja HTTP-tilakoodit

Sovellusvirheet käyttävät application/problem+json-muotoa (RFC 9457). Käsittele virheet pysyvien code- ja action-kenttien perusteella, älä detail-kentän selitystekstin perusteella. Validointivirheissä errors sisältää kenttien JSON Pointer -sijainnit. Ilmoita request_id tukipyynnössä. Välityspalvelin- tai yhteysvirheen vastaus voi olla erilainen; tarkista Content-Type ennen JSON-jäsennystä.

Seuraava synteettinen 422-esimerkki näyttää virheellisen sähköpostisyntaksin ennen laskutusta. Julkisessa virheluettelossa luetellaan jokainen koodi, tila, selitys ja toimenpideehdotus.

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

• Täysi v2-virheluettelo

Uudelleenyritykset ja laskutus

Jokainen ennustepyyntö on uusi operaatio, mukaan lukien identtinen pyyntö lähetetään uudelleen. Jokaiseen pyyntöön sovelletaan normaaleja luottosääntöjä. Kaksoispyyntösuojaa ei ole, joten vältä automaattisia uudelleenyrityksiä yhteyden katkeamisen tai tuntemattoman tuloksen jälkeen.

Jos haluat 429-vastauksen, odota Retry-After ennen uuden pyynnön lähettämistä. Jos ennuste epäonnistuu, tarkista ensin code, action ja meta.usage.billing_status. Jos kyseessä on billing_reconciliation_required tai vahvistamaton laskutus, ota yhteyttä request_id-tukeen ennen kuin yrität uudelleen.

Osittain onnistunut erä voi palauttaa HTTP 200. Tarkista jokainen tuote ja lähetä uudelleen vain epäonnistuneet tuotteet laskutuksen vahvistamisen jälkeen; onnistuneet tuotteet laskutetaan uudelleen, jos ne lähetetään uudelleen.

X-Request-ID ja meta.request_id tunnistavat nykyisen HTTP-yrityksen. Lue nykyinen saldo /usage. HEAD ei aloita laskutettavaa ennustetta. Ennuste ja tilivastaukset eivät ole välimuistissa.

Asiakkaiden tulee sietää additiivisia vastekenttiä ja säilyttää null-arvot, kun tietoja ei ole saatavilla.

Pyyntörajat

Käsittele HTTP 429 ja Retry-After sen sijaan, että olettaisit, että pyynnöt hyväksytään aina näillä enimmäismäärillä. Palvelukapasiteetti on jaettu. Näytetyt arvot ovat tämänhetkisiä palvelun oletusasetuksia. Nopeusrajoitusvastauksia ovat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset (Unix sekuntia). Retry-After on viive sekunneissa. Nämä otsikot kuvaavat pyyntörajoja, eivät jäljellä olevia krediittejä. Jopa ilmainen /usage-luku lasketaan nopeusrajoissa.