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), request_id, timestamps y cuerpo del error.

Formato de error

Todos los errores de la API de QRwey! siguen una estructura consistente:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation",
    "details": [
      {
        "field": "amount",
        "code": "INVALID_FORMAT",
        "message": "amount must be a positive number"
      }
    ],
    "request_id": "req_01JCFG..."
  }
}
CampoDescripción
codeIdentificador estable del error (usa este campo como clave programática)
messageDescripción legible del error
detailsInformación adicional por campo (si aplica)
request_idIdentificador único de la solicitud para trazabilidad y soporte

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

Códigos HTTP

CódigoSignificadoCuándo se usa
200OKGET exitoso
201CreatedPOST que crea un recurso exitosamente
400Bad RequestSintaxis inválida, campos faltantes o tipos incorrectos
401UnauthorizedAutenticación ausente o inválida
403ForbiddenAutenticación válida pero permisos insuficientes
404Not FoundRecurso no encontrado
409ConflictConflicto de estado (duplicado, ya consumido)
422Unprocessable EntitySintaxis válida pero error semántico o de regla de negocio
429Too Many RequestsLímite de tasa excedido
500Internal Server ErrorError interno inesperado
502Bad GatewayFallo en servicio upstream (SAT, PAC)
503Service UnavailableServicio temporalmente no disponible

Errores por endpoint

Generar QR (POST /v1/qrs)

StatusCódigoDescripciónQué hacer
400VALIDATION_ERRORCampos requeridos faltantes o tipos de datos inválidosCorregir request, no reintentar
400EXPIRED_QR_DATEexpires_at está en el pasadoCorregir la fecha de expiración
401UNAUTHORIZEDAPI Key inválida o ausenteVerificar X-API-Key y el ambiente
404STORE_NOT_FOUNDNo se encontró la tienda con el store_uid proporcionadoVerificar el store_uid
409DUPLICATE_IDEMPOTENCY_KEYidempotency-key ya utilizada con datos distintosUsar un nuevo idempotency-key o verificar el request original
422STORE_DISABLEDLa tienda está deshabilitada o su CSD es inválido/expiradoVerificar configuración de la tienda y CSD
422INVALID_SAT_CATALOG_VALUEValor de catálogo SAT inválidoVerificar claves SAT en el request
5xx—Error temporal del servidorReintentar con el mismo idempotency-key

Obtener detalle de QR (GET /v1/qrs/{qrId})

StatusCódigoDescripciónQué hacer
401UNAUTHORIZEDAPI Key inválida o ausenteVerificar X-API-Key y el ambiente
404RESOURCE_NOT_FOUNDQR no encontradoVerificar que el qr_id sea correcto
422STORE_CONFIGURATION_ERRORConfiguración de la tienda o emisor incorrectaRevisar code y message en la respuesta

Códigos de error comunes (plataforma)

CódigoHTTPDescripción
VALIDATION_ERROR400Uno o más campos fallaron validación
INVALID_RFC_FORMAT400Formato de RFC inválido
INVALID_CSD_FORMAT400Formato de certificado CSD inválido
AUTHENTICATION_REQUIRED401No se proporcionó autenticación
INVALID_TOKEN401Token inválido o expirado
INSUFFICIENT_PERMISSIONS403Token sin permisos suficientes
RESOURCE_NOT_FOUND404Recurso no encontrado
RFC_ALREADY_EXISTS409RFC ya registrado en esta cuenta
QR_ALREADY_INVOICED409No se puede modificar un QR ya facturado
CSF_VALIDATION_FAILED422Validación de CSF con el SAT falló
CSD_RFC_MISMATCH422CSD no corresponde al RFC
CSD_EXPIRED422Certificado CSD expirado
RATE_LIMIT_EXCEEDED429Demasiadas solicitudes
SAT_SERVICE_UNAVAILABLE502Servicios del SAT no disponibles
PAC_SERVICE_UNAVAILABLE502Servicios del PAC no disponibles

Estrategia de reintentos

Reintentar SOLO si:

  • Timeout (sin respuesta)
  • 500–503
  • 429 (respetando backoff)

No reintentar si:

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

Para verificar si un QR expiró, consulta GET /v1/qrs/{qrId} y revisa el campo status: EXPIRED.

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 (sugeridos)

Evita mostrar mensajes técnicos al usuario final. Mejor:

  • status: EXPIRED: "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)
  • 502: "Los servicios fiscales están temporalmente fuera de servicio. Intenta más tarde."

Logging y trazabilidad

Recomendación mínima de logs por request:

  • Método + path
  • Timestamp inicio/fin
  • Código HTTP
  • request_id de la respuesta de error
  • idempotency-key (si aplica)
  • code y message del error

Registra siempre el request_id devuelto por QRwey! — es la clave para soporte y escalación.

Checklist para producción

  • Manejas explícitamente 404, 409, 422 y los diferentes estatus del QR
  • Manejas 502 y 503 (servicios SAT/PAC)
  • Reintentas solo en timeouts, 429 y 5xx
  • Reusas el mismo idempotency-key en reintentos
  • Mensajes al usuario son claros y no técnicos
  • Logs incluyen request_id, idempotency-key y timestamps
  • Usas code (no message) como clave programática para lógica de negocio

¿Qué sigue?

Previous page
Next page