GenderAPI.io V2: errores, límites y reintentos

Errores y códigos de estado HTTP

Los errores de la aplicación usan application/problem+json (RFC 9457). Gestiona los errores mediante code y action, cuyos valores son estables, y no mediante el texto de detail. En los errores de validación, errors incluye ubicaciones JSON Pointer de los campos afectados. Facilita request_id al contactar con soporte. Los fallos de conexión o proxy pueden devolver otro contenido; compruebe Content-Type antes de interpretarlo como JSON.

El siguiente ejemplo sintético 422 muestra una sintaxis de correo electrónico no válida antes de la facturación. El catálogo público de errores enumera todos los códigos, estados, explicaciones y acciones sugeridas.

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

• Catálogo completo de errores V2

Campos de la respuesta de error

Acceso, facturación y metadatos de la solicitud

Reintentos y facturación

Cada solicitud de predicción es una nueva operación, incluida una solicitud idéntica enviada nuevamente. Se aplican reglas de crédito normales a cada solicitud. No existe protección contra solicitudes duplicadas, así que evite los reintentos automáticos después de una pérdida de conexión o de un resultado desconocido.

Ante HTTP 429, espera el tiempo indicado en Retry-After. Si falla una predicción, revisa primero code, action y meta.usage.billing_status. Ante billing_reconciliation_required o un cobro unconfirmed, contacta con soporte e incluye request_id antes de repetir la solicitud.

Un lote parcialmente exitoso puede devolver HTTP 200. Comprueba cada elemento y vuelva a enviar solo los elementos fallidos después de confirmar la facturación; Los elementos exitosos se facturarán nuevamente si se vuelven a enviar.

X-Request-ID y meta.request_id identifican el intento actual de HTTP. Lee /usage para conocer el saldo actual. HEAD no inicia una predicción facturable. Las predicciones y las respuestas de la cuenta no se pueden almacenar en caché.

Los clientes deben tolerar campos de respuesta aditivos y preservar los valores null cuando la información no está disponible.

Límites de solicitudes

Gestiona HTTP 429 y Retry-After en lugar de asumir que las solicitudes siempre se aceptarán en estos límites máximos. La capacidad de servicio es compartida. Los valores mostrados son los valores predeterminados del servicio actual. Las respuestas de límite de velocidad incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos Unix). Retry-After es un retraso en segundos. Estos encabezados describen los límites de solicitud, no los créditos restantes. Incluso la lectura gratuita de /usage cuenta para los límites de velocidad.