API v2 errors and retries

Errors and HTTP status codes

Application errors use application/problem+json (RFC 9457). Branch on the stable code and action, not the human-readable detail. Validation errors include JSON Pointer locations in errors. Include request_id when contacting support. Proxy or transport failures can return a different body, so check Content-Type before parsing JSON.

The following synthetic 422 example shows invalid email syntax before billing. The public error catalog lists every code, status, explanation and suggested action.

HTTP status	Typical meaning	Next step
400 / 413 / 415	Malformed JSON, oversized body or unsupported media type.	Correct the request.
401 / 403	Access rejected, account restriction or insufficient credits.	Inspect code; correct access or replenish credits / wait for trial reset.
422	Invalid input or incompatible options.	Correct the fields identified in errors.
404 / 405	Unknown route or unsupported HTTP method.	Check the endpoint path and the Allow response header.
429	Rate or concurrency limit.	Wait for Retry-After before sending another request.
500	Unexpected server failure.	Contact support with request_id; check billing before retrying.
502 / 503 / 504	Provider, dependency, billing or timeout failure.	Inspect code, action and billing_status before retrying.

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

Full v2 error catalog

Retries and billing

Every prediction request is a new operation, including an identical request sent again. Normal credit rules apply to each request. There is no duplicate-request protection, so avoid automatic retries after a connection loss or an unknown outcome.

For a 429 response, wait for Retry-After before sending another request. For prediction failures, inspect code, action and meta.usage.billing_status first. For billing_reconciliation_required or unconfirmed billing, contact support with request_id before retrying.

A partially successful batch may return HTTP 200. Check each item and resubmit only failed items after billing is confirmed; successful items would be billed again if resubmitted.

X-Request-ID and meta.request_id identify the current HTTP attempt. Read /usage for the current balance. HEAD does not start a billable prediction. Prediction and account responses are not cacheable.

Clients should tolerate additive response fields and preserve null values when information is unavailable.

Request limits

Handle HTTP 429 and Retry-After rather than assuming requests will always be accepted at these ceilings. Service capacity is shared. The values shown are the current service defaults. Rate-limit responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Retry-After is a delay in seconds. These headers describe request limits, not remaining credits. Even the free /usage read counts toward rate limits.

Limit	Value
JSON request body	64 KiB maximum
Prediction value	1–254 characters
Batch	50 items with an API key; 10 with the IP trial
Account rate	120 requests per minute
IP rate	600 requests per minute
Concurrent operations	2 per account; 16 across the service