GenderAPI.io V2: Fel, gränser och nya försök

Fel och HTTP-statuskoder

Applikationsfel använder application/problem+json (RFC 9457). Utgå från de stabila fälten code och action, inte från den läsbara texten i detail. Vid valideringsfel innehåller errors JSON Pointer-platser för de berörda fälten. Ange request_id när du kontaktar supporten. Fel i en proxy eller vid överföringen kan ge ett annat svarsinnehåll, så kontrollera Content-Type innan du tolkar JSON.

Följande syntetiska 422-exempel visar ogiltig e-postsyntax före debitering. Den offentliga felkatalogen listar alla koder, statusar, förklaringar och föreslagna åtgärder.

HTTP-status	Vanlig betydelse	Nästa steg
400 / 413 / 415	Felaktig JSON, för stor kropp eller mediatyp som inte stöds.	Rätta förfrågan.
401 / 403	Åtkomst nekad, kontobegränsning eller otillräckliga krediter.	Kontrollera code; rätta åtkomsten, fyll på krediter eller vänta tills provperioden återställs.
422	Ogiltiga indata eller alternativ som inte kan kombineras.	Rätta fälten som anges i errors.
404 / 405	Okänd rutt eller HTTP-metod som inte stöds.	Kontrollera endpointens sökväg och svarsrubriken Allow.
429	Gräns för antal eller samtidiga förfrågningar.	Vänta den tid som anges i Retry-After innan du skickar nästa förfrågan.
500	Oväntat serverfel.	Kontakta supporten med request_id och kontrollera debiteringen innan du försöker igen.
502 / 503 / 504	Fel hos leverantören, i ett beroende eller i debiteringen, eller en tidsgräns som överskridits.	Kontrollera code, action och billing_status innan du försöker igen.

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

Fullständig felkatalog för V2

Fält i felsvaret

Fält	Typ	Kan vara null	Exempel	Beskrivning
`type`	`string`	Nej	`"urn:genderapi:problem:validation_error"`	URI som identifierar problemtypen.
`title`	`string`	Nej	`"validation error"`	Kort, läsbar rubrik för felet.
`status`	`integer`	Nej	`422`	HTTP-statuskod.
`detail`	`string`	Nej	`"The request does not match the schema."`	Förklaring av just det här felet.
`instance`	`string`	Nej	`"urn:uuid:550e8400-e29b-41d4-a716-446655440000"`	Identifierare för den misslyckade förfrågan.
`code`	`string`	Nej	`"validation_error"`	Stabil, maskinläsbar felkod.
`request_id`	`string`	Nej	`"550e8400-e29b-41d4-a716-446655440000"`	Unik identifierare för det här HTTP-försöket; skickas även i X-Request-ID.
`documentation`	`string`	Nej	`"https://api.genderapi.io/api/v2/errors"`	Länk till felkatalogen, om den anges.
`action`	`string`	Nej	`"correct_request"`	Föreslagen åtgärd, om den definieras i felkatalogen.
`errors`	`array<object>`	Nej	`[{"pointer":"/value","message":"must NOT have fewer than 1 characters"}]`	Valideringsproblem, om de finns. Varje post innehåller pointer och message.
`errors[].pointer`	`string`	Nej	`"/value"`	JSON Pointer som pekar ut de ogiltiga indata.
`errors[].message`	`string`	Nej	`"must NOT have fewer than 1 characters"`	Förklaring av valideringsproblemet.

Metadata om åtkomst, debitering och förfrågan

Fält	Typ	Kan vara null	Exempel	Beskrivning
`meta.request_id`	`string`	Nej	`"550e8400-e29b-41d4-a716-446655440000"`	Unik identifierare för det här HTTP-försöket; skickas även i X-Request-ID.
`meta.duration_ms`	`integer`	Nej	`42`	Bearbetningstid för förfrågan i millisekunder.
`meta.access.mode`	`string`	Nej	`"api_key"`	api_key, ip_trial eller unauthenticated. Kontrollera att api_key rapporteras när du använder ett betalt konto.
`meta.access.reason`	`string`	Ja	`null`	Orsak till att IP-provperioden användes: api_key_missing, api_key_invalid eller api_key_not_found; annars null.
`meta.usage.charged_credits`	`integer`	Ja	`1`	Debiterade krediter netto. 0 före debitering eller efter en bekräftad fullständig återbetalning; null när debiteringen är obekräftad.
`meta.usage.remaining_credits`	`integer`	Ja	`99`	Saldo när åtgärden slutförs. Kan vara negativt; null om saldot saknas eller debiteringen är obekräftad.
`meta.usage.billing_status`	`string`	Nej	`"confirmed"`	not_charged, confirmed eller unconfirmed. Kontrollera detta innan du gör ett nytt försök med en misslyckad prediktion.
`meta.usage.resets_at`	`string`	Ja	`"2026-09-27T12:00:00.000Z"`	Tidpunkt i UTC (ISO 8601) då IP-provperioden återställs; null för konton med API-nyckel eller om tidpunkten är okänd.
`meta.usage.limit`	`integer`	Ja	`10`	Kvot för IP-provperioden; null för konton med API-nyckel.
`meta.usage.period_seconds`	`integer`	Ja	`86400`	IP-provperiodens tidsfönster i sekunder; null för konton med API-nyckel.

Nya försök och debitering

Varje prediktionsförfrågan är en ny åtgärd, även en identisk förfrågan som skickas igen. De vanliga kreditreglerna gäller för varje förfrågan. Det finns inget skydd mot dubblerade förfrågningar, så undvik automatiska nya försök efter ett avbrott i anslutningen eller ett oklart utfall.

Vid ett 429-svar väntar du den tid som anges i Retry-After innan du skickar nästa förfrågan. Vid misslyckade prediktioner kontrollerar du först code, action och meta.usage.billing_status. Vid billing_reconciliation_required eller obekräftad debitering kontaktar du supporten med request_id innan du försöker igen.

En delvis lyckad batch kan returnera HTTP 200. Kontrollera varje post och skicka bara om de misslyckade posterna när debiteringen är bekräftad; lyckade poster skulle debiteras igen om de skickades om.

X-Request-ID och meta.request_id identifierar det aktuella HTTP-försöket. Läs aktuellt saldo via /usage. HEAD startar ingen debiterbar prediktion. Svar på prediktioner och kontoförfrågningar cachelagras inte.

Klienter bör tåla nya svarsfält och behålla null-värden när uppgifter saknas.

Gränser för förfrågningar

Hantera HTTP 429 och Retry-After i stället för att utgå från att förfrågningar alltid godtas upp till dessa gränser. Tjänstens kapacitet delas. Värdena är tjänstens nuvarande standardvärden. Svar vid begränsning innehåller X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset (Unix-sekunder). Retry-After är en väntetid i sekunder. Rubrikerna beskriver gränser för förfrågningar, inte återstående krediter. Även den kostnadsfria kontrollen via /usage räknas mot gränserna.

Gräns	Värde
JSON-kropp i förfrågan	högst 64 KiB
Värde för prediktionen	1–254 tecken
Batch	50 poster med API-nyckel; 10 i IP-provperioden
Gräns per konto	120 förfrågningar per minut
Gräns per IP-adress	600 förfrågningar per minut
Samtidiga åtgärder	2 per konto; 16 för hela tjänsten