Handle errors and limitations
Design for validation failures, service availability, limits, and uncertain network outcomes.
Status codes
| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid request input | Correct the request; do not retry unchanged. |
| 401 | Missing, invalid, or inactive API key | Check x-api-key and key rotation. |
| 403 | live_mode_not_activated — live account pending VEX Pay review or suspended | Use your Test key; request go-live from the portal (see Going live). Do not retry. |
| 403 | This method is not enabled on your account (advanced débito/crédito endpoints) | Use a routed endpoint or ask VEXPay ops to allow the method; do not retry unchanged. |
| 404 | Payment or resource not found for tenant | Check the ID and tenant scope. |
| 422 | The banking network rejected the operation | Inspect the error code and do not retry unchanged. |
| 422 | insufficient_balance — the payout is larger than your available balance; part of it may be on the 24h hold (heldVes / heldUsdt / heldCop, nextReleaseAt) | Pay out at most the available amount, or retry after nextReleaseAt. See Balances, holds and payouts. |
| 503 | Payment service unavailable | Retry later after confirming the original payment status. |
| 5xx | Gateway or banking-network failure | Treat the outcome as uncertain; look up the payment. |
Current limitations
- C2P reversal is the only supported reversal flow.
- Webhook delivery is one attempt with no automatic retry and a 10-second timeout.
- On payments, externalRef is correlation only; use Idempotency-Key for safe retries. A C2P, VPOS or débito charge whose externalRef already has a COMPLETED payment is refused with 409 external_ref_already_paid (paymentId in the body). On merchants and payouts externalRef is required and is the resource idempotency key (max 64, unique per tenant).
- The tenant application gathers C2P tokens; the backend does not message customers.
Recover safely
- Record the attempt
Persist your order reference and any returned gateway payment ID.
- Resolve uncertainty
Look up by payment ID, or externalRef when no ID was received.
- Retry deliberately
Only submit another mutation after confirming the original did not complete.