API V2:n 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, joka hylätään ennen laskutusta. Julkinen virheluettelo sisältää jokaisen koodin, tilan, selityksen ja suositellun toimenpiteen.

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

• Koko V2-virheluettelo

Virhevastauksen kentät

Käyttöoikeus, veloitus ja pyynnön metatiedot

Uudelleenyritykset ja laskutus

Jokainen ennustepyyntö on uusi toiminto, myös uudelleen lähetetty identtinen pyyntö. Jokaiseen pyyntöön sovelletaan tavallisia krediittisääntöjä. Päällekkäisiltä pyynnöiltä ei ole suojaa, joten vältä automaattisia uudelleenyrityksiä yhteyden katkettua tai kun tulos on epäselvä.

Jos saat 429-vastauksen, odota Retry-After-otsakkeen ilmoittama aika ennen uuden pyynnön lähettämistä. Jos ennuste epäonnistuu, tarkista ensin code, action ja meta.usage.billing_status. Jos tila on billing_reconciliation_required tai laskutusta ei ole vahvistettu, ota yhteyttä tukeen ja ilmoita request_id ennen uutta yritystä.

Osittain onnistunut erä voi palauttaa HTTP 200 -vastauksen. Tarkista jokainen kohde ja lähetä uudelleen vain epäonnistuneet kohteet, kun laskutus on vahvistettu; onnistuneet kohteet laskutettaisiin uudelleen, jos ne lähetettäisiin uudelleen.

X-Request-ID ja meta.request_id yksilöivät nykyisen HTTP-yrityksen. Lue nykyinen saldo reitiltä /usage. HEAD ei käynnistä laskutettavaa ennustetta. Ennuste- ja tilivastauksia ei tallenneta välimuistiin.

Asiakasohjelmien tulee sietää vastaukseen lisättäviä uusia kenttiä ja säilyttää null-arvot, kun tietoa ei ole saatavilla.

Pyyntörajat

Käsittele HTTP 429 ja Retry-After äläkä oleta, että pyynnöt hyväksytään aina näihin ylärajoihin asti. Palvelun kapasiteetti on jaettu. Näytetyt arvot ovat palvelun nykyiset oletukset. Pyyntörajavastaukset sisältävät otsakkeet X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset (Unix-sekunteina). Retry-After on viive sekunteina. Nämä otsakkeet kuvaavat pyyntörajoja, eivät jäljellä olevia krediittejä. Myös maksuton /usage-luku lasketaan pyyntörajoihin.