Errores y reintentos de API v2

Errores y códigos de estado HTTP

Los errores de la aplicación usan application/problem+json (RFC 9457). Gestione 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. Facilite 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

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.

Para obtener una respuesta 429, espere Retry-After antes de enviar otra solicitud. Para detectar fallas en la predicción, inspeccione primero code, action y meta.usage.billing_status. Para billing_reconciliation_required o facturación no confirmada, comuníquese con soporte con request_id antes de volver a intentarlo.

Un lote parcialmente exitoso puede devolver HTTP 200. Verifique 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. Lea /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

Maneje 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.