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. |
| 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. |
| 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.
- externalRef correlates records but does not provide idempotency.
- 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.