Skip to content
/
Manejo de errores
Last updated

Manejo de errores

Integrar una API en producción implica manejar fallos de red, validaciones y reglas de negocio. Esta guía te ayuda a interpretar los errores de QRwey! y definir una estrategia estable de reintentos, mensajes al usuario y registro para soporte.

Principios

  1. No todos los errores se reintentan.
    Reintentar un 4xx suele ser un error (excepto casos muy específicos).

  2. Distingue entre fallos temporales y definitivos.
    5xx y timeouts suelen ser temporales. 4xx suelen ser definitivos.

  3. Registra contexto suficiente para soporte.
    Incluye endpoint, Idempotency-Key (si aplica), timestamps y cuerpo del error.

Formato de error

Dependiendo del endpoint, QRwey! puede devolver un JSON con campos como:

  • code: identificador del error
  • message: descripción legible
  • details: información adicional (si aplica)

Si tu integración depende del contenido del error, usa code como clave estable y evita parsear textos libres en message.

Tabla de errores comunes

Código HTTPQué significaQué hacer
400 Bad RequestValidación: campos faltantes, tipos inválidos, firma/params incorrectosCorrige request, no reintentar
401 UnauthorizedAPI Key inválida o ausenteVerifica X-API-Key y ambiente
404 Not FoundQR inválido / no existe / revocadoTratar como “QR inválido”
409 ConflictOperación en conflicto: QR ya consumido o idempotenciaNo reintentar; mostrar “ya utilizado”
410 GoneQR expiradoSolicitar generar un QR nuevo
422 Unprocessable EntityRegla de negocio/configuración fiscalRevisar code y message
429 Too Many RequestsLímite de tasa (si aplica)Esperar y reintentar con backoff
500–599Error interno temporalReintentar con backoff y límite

Errores por endpoint

Generar QR (POST /api/v1/qrs)

Errores típicos:

  • 400: request inválido (campos fiscales, expires_at, etc.)
  • 401: API Key inválida
  • 409: conflicto por idempotencia o duplicado lógico
  • 422: configuración fiscal incompleta o reglas no cumplidas
  • 5xx: error temporal

Acción recomendada:

  • Si hay timeout/5xx → reintentar con el mismo Idempotency-Key
  • Si hay 4xx → corregir request / configuración, no reintentar en loop

Resolver QR (GET /api/v1/qrs)

Errores típicos:

  • 400: v/t/m inválidos o firma incorrecta
  • 404: token no encontrado / revocado
  • 409: QR ya consumido (si aplica)
  • 410: QR expirado
  • 422: regla de negocio

Acción recomendada:

  • 410 → pedir al comercio generar un QR nuevo
  • 409 → mostrar “QR ya utilizado”
  • 404 → mostrar “QR inválido”
  • 400 → revisar extracción de parámetros desde qr_content

Estrategia de reintentos (recomendada)

Reintentar SOLO si:

  • Timeout (sin respuesta)
  • 500–599
  • 429 (si aplica)

No reintentar si:

  • Cualquier 400–499 (salvo 429)
  • 409 (conflicto) sin revisar lógica
  • 410 (expirado)
  • 404 (no encontrado)

Backoff recomendado

Para reintentos temporales:

  • 1er retry: 1s
  • 2do retry: 2s
  • 3er retry: 4s
  • 4to retry: 8s

Límite recomendado:

  • Máximo 3–5 reintentos
  • Máximo 30s de ventana total

Mensajes al usuario final (MX, sugeridos)

Evita mostrar mensajes técnicos como “410 Gone”. Mejor:

  • 410: “Este QR ya expiró. Solicita uno nuevo.”
  • 409: “Este QR ya fue utilizado.”
  • 404: “QR inválido. Verifica el código e inténtalo de nuevo.”
  • 401: “No se pudo validar la solicitud.” (solo si aplica al comercio)

Logging y trazabilidad

Recomendación mínima de logs por request:

  • Método + path (sin exponer tokens completos)
  • Timestamp inicio/fin
  • Código HTTP
  • Idempotency-Key (si aplica)
  • Resumen de code y message del error

Evita loguear t y m completos; si necesitas trazabilidad, loguea solo un hash o una versión truncada.

Checklist para producción

  • Manejas explícitamente 404, 409, 410, 422
  • Reintentas solo en timeouts y 5xx
  • Reusas el mismo Idempotency-Key en reintentos
  • Mensajes al usuario son claros y no técnicos
  • Logs suficientes sin exponer secretos

¿Qué sigue?

Previous page
Next page