Fouten en HTTP-statuscodes
Applicatiefouten gebruiken application/problem+json (RFC 9457). Baseer uw logica op de stabiele velden code en action, niet op de leesbare tekst in detail. Bij validatiefouten bevat errors de JSON Pointers van de betreffende velden. Vermeld request_id wanneer u contact opneemt met support. Bij fouten van een proxy of in de verbinding kan de body van het antwoord afwijken: controleer Content-Type voordat u de JSON verwerkt.
Het volgende synthetische 422-voorbeeld toont een ongeldige e-mailsyntaxis die vóór de afschrijving wordt gedetecteerd. De openbare foutencatalogus vermeldt alle codes, statussen, uitleg en aanbevolen acties.
| HTTP-status | Gebruikelijke betekenis | Volgende stap |
|---|---|---|
| 400 / 413 / 415 | Ongeldige JSON, te grote body of niet-ondersteund mediatype. | Corrigeer het verzoek. |
| 401 / 403 | Toegang geweigerd, beperking van het account of onvoldoende credits. | Controleer code; corrigeer de toegang, vul credits aan of wacht tot de IP-proefperiode wordt hersteld. |
| 422 | Ongeldige invoer of opties die niet samengaan. | Corrigeer de velden die in errors worden vermeld. |
| 404 / 405 | Onbekende route of niet-ondersteunde HTTP-methode. | Controleer het pad van het endpoint en de antwoordheader Allow. |
| 429 | Limiet voor het aantal verzoeken of gelijktijdige bewerkingen. | Wacht de tijd uit die in Retry-After staat voordat u een nieuw verzoek verstuurt. |
| 500 | Onverwachte serverfout. | Neem contact op met support en vermeld request_id; controleer de afschrijving voordat u het opnieuw probeert. |
| 502 / 503 / 504 | Fout bij de provider, een afhankelijkheid of de afschrijving, of een time-out. | Controleer code, action en billing_status voordat u het opnieuw probeert. |
{
"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
}
}
}Velden van het foutantwoord
| Veld | Type | Kan null zijn | Voorbeeld | Beschrijving |
|---|---|---|---|---|
type | string | Nee | "urn:genderapi:problem:validation_error" | URI die het type probleem aanduidt. |
title | string | Nee | "validation error" | Korte titel van de fout, leesbaar voor mensen. |
status | integer | Nee | 422 | HTTP-statuscode. |
detail | string | Nee | "The request does not match the schema." | Uitleg van deze specifieke fout. |
instance | string | Nee | "urn:uuid:550e8400-e29b-41d4-a716-446655440000" | Identificatie van het mislukte verzoek. |
code | string | Nee | "validation_error" | Stabiele, machineleesbare foutcode. |
request_id | string | Nee | "550e8400-e29b-41d4-a716-446655440000" | Unieke identificatie van deze HTTP-poging; wordt ook verstuurd in X-Request-ID. |
documentation | string | Nee | "https://api.genderapi.io/api/v2/errors" | Link naar de foutencatalogus, indien aanwezig. |
action | string | Nee | "correct_request" | Aanbevolen herstelactie, indien gedefinieerd in de foutencatalogus. |
errors | array<object> | Nee | [{"pointer":"/value","message":"must NOT have fewer than 1 characters"}] | Validatieproblemen, indien beschikbaar. Elk item bevat pointer en message. |
errors[].pointer | string | Nee | "/value" | JSON Pointer die de ongeldige invoer aanwijst. |
errors[].message | string | Nee | "must NOT have fewer than 1 characters" | Uitleg van het validatieprobleem. |
Metadata over toegang, afschrijving en verzoek
| Veld | Type | Kan null zijn | Voorbeeld | Beschrijving |
|---|---|---|---|---|
meta.request_id | string | Nee | "550e8400-e29b-41d4-a716-446655440000" | Unieke identificatie van deze HTTP-poging; wordt ook verstuurd in X-Request-ID. |
meta.duration_ms | integer | Nee | 42 | Verwerkingstijd van het verzoek in milliseconden. |
meta.access.mode | string | Nee | "api_key" | api_key, ip_trial of unauthenticated. Controleer bij een betaald account of api_key wordt vermeld. |
meta.access.reason | string | Ja | null | Reden om naar de IP-proefperiode over te schakelen: api_key_missing, api_key_invalid of api_key_not_found; anders null. |
meta.usage.charged_credits | integer | Ja | 1 | Netto afgeschreven credits. Nul vóór de afschrijving of na een bevestigde volledige terugboeking; null als de afschrijving niet is bevestigd. |
meta.usage.remaining_credits | integer | Ja | 99 | Saldo bij voltooiing van de bewerking. Kan negatief zijn; null als het niet beschikbaar is of de afschrijving niet is bevestigd. |
meta.usage.billing_status | string | Nee | "confirmed" | not_charged, confirmed of unconfirmed. Controleer dit voordat u een mislukte voorspelling herhaalt. |
meta.usage.resets_at | string | Ja | "2026-09-27T12:00:00.000Z" | Tijdstip waarop de IP-proefperiode wordt hersteld, in UTC (ISO 8601); null voor accounts met een API-sleutel of als het onbekend is. |
meta.usage.limit | integer | Ja | 10 | Tegoed van de IP-proefperiode; null voor accounts met een API-sleutel. |
meta.usage.period_seconds | integer | Ja | 86400 | Duur van de periode van de IP-proefperiode in seconden; null voor accounts met een API-sleutel. |
Nieuwe pogingen en afschrijvingen
Elk voorspellingsverzoek is een nieuwe bewerking, ook als u een identiek verzoek opnieuw verstuurt. Op elk verzoek zijn de normale regels voor credits van toepassing. Er is geen bescherming tegen dubbele verzoeken: vermijd daarom automatische nieuwe pogingen na een verbroken verbinding of een onbekende uitkomst.
Wacht bij een 429-antwoord de tijd uit die in Retry-After staat voordat u een nieuw verzoek verstuurt. Controleer bij mislukte voorspellingen eerst code, action en meta.usage.billing_status. Neem bij billing_reconciliation_required of een onbevestigde afschrijving contact op met support en vermeld request_id voordat u het opnieuw probeert.
Een batch die slechts gedeeltelijk is geslaagd, kan HTTP 200 teruggeven. Controleer elk item en verstuur na bevestiging van de afschrijving alleen de mislukte items opnieuw; geslaagde items zouden nogmaals worden afgeschreven.
X-Request-ID en meta.request_id identificeren de huidige HTTP-poging. Lees het huidige saldo via /usage. HEAD start geen betaalde voorspelling. Antwoorden met voorspellingen en accountgegevens worden niet in de cache opgeslagen.
Clients moeten nieuwe velden in het antwoord accepteren en null-waarden behouden wanneer informatie niet beschikbaar is.
Verzoeklimieten
Verwerk HTTP 429 en Retry-After in plaats van ervan uit te gaan dat verzoeken tot deze maximumwaarden altijd worden geaccepteerd. De capaciteit van de dienst wordt gedeeld. De getoonde waarden zijn de huidige standaardinstellingen van de dienst. Antwoorden bij het bereiken van een limiet bevatten X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (Unix-seconden). Retry-After is een wachttijd in seconden. Deze headers beschrijven de verzoeklimieten, niet de resterende credits. Ook het gratis opvragen van /usage telt mee voor de verzoeklimieten.
| Limiet | Waarde |
|---|---|
| JSON-body van het verzoek | maximaal 64 KiB |
| Waarde voor de voorspelling | 1–254 tekens |
| Batch | 50 items met een API-sleutel; 10 met de IP-proefperiode |
| Limiet per account | 120 verzoeken per minuut |
| Limiet per IP-adres | 600 verzoeken per minuut |
| Gelijktijdige bewerkingen | 2 per account; 16 voor de hele dienst |