Maneja errores y limitaciones
Diseña tu integración para fallas de validación, disponibilidad del servicio, límites y resultados inciertos de la red.
Códigos de estado
| Estado | Significado | Acción |
|---|---|---|
| 400 | Datos de solicitud inválidos | Corrige la solicitud; no la reintentes sin cambios. |
| 401 | Clave de API ausente, inválida o inactiva | Revisa x-api-key y la rotación de claves. |
| 404 | No se encontró el pago o recurso para el tenant | Revisa el ID y el alcance del tenant. |
| 403 | live_mode_not_activated — cuenta Live pendiente de revisión de VEX Pay o suspendida | Usa tu clave Test; solicita salir a producción desde el portal (ver Salir a producción). No reintentes. |
| 403 | Este método no está habilitado en tu cuenta (endpoints avanzados de débito/crédito) | Usa un endpoint enrutado o pide a operaciones de VEXPay que habiliten el método; no reintentes sin cambios. |
| 422 | La red bancaria rechazó la operación | Revisa el código de error y no reintentes la solicitud sin cambios. |
| 422 | insufficient_balance: el payout supera tu saldo disponible; parte puede estar en la retención de 24 h (heldVes / heldUsdt / heldCop, nextReleaseAt) | Envía como máximo el monto disponible o reintenta después de nextReleaseAt. Ver Saldos, retenciones y payouts. |
| 503 | El servicio de pagos no está disponible | Reintenta más tarde después de confirmar el estado del pago original. |
| 5xx | Falla del gateway o de la red bancaria | Considera el resultado incierto y consulta el pago. |
Limitaciones actuales
- El reverso de C2P es el único flujo de reverso compatible.
- La entrega de webhooks se intenta una sola vez, sin reintento automático y con un tiempo de espera de 10 segundos.
- En pagos, externalRef es solo correlación; usa Idempotency-Key para reintentos seguros. Un cobro C2P, VPOS o débito cuyo externalRef ya tiene un pago COMPLETED se rechaza con 409 external_ref_already_paid (paymentId en el cuerpo). En comerciantes y payouts externalRef es obligatorio y actúa como clave de idempotencia del recurso (máx. 64, único por tenant).
- La aplicación del tenant obtiene los tokens C2P; el backend no se comunica con los clientes.
Recupérate de forma segura
- Registra el intento
Guarda la referencia de tu pedido y cualquier ID de pago del gateway que se haya devuelto.
- Resuelve la incertidumbre
Consulta por ID de pago o por externalRef cuando no hayas recibido un ID.
- Reintenta deliberadamente
Envía otra operación de escritura solo después de confirmar que la original no se completó.