GenderAPI.io V2: Errors, limits 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.

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

Error response fields

Access, billing and request metadata

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.