Errors and Retries
Error classes, safe retry, and operational recovery.
In payment APIs, "retry on every error" gets expensive fast. First classify the error, then decide what to show the user.
Decline and code list: Testing Declines.
Classes
| Group | What to do |
|---|---|
| 4xx validation | Fix payload; no retry |
| 401/403 | Key or permission |
| 409 | Idempotency conflict; read result with same key |
| 5xx / timeout | Limited backoff; same idempotency key |
Confirm and decline
After a decline, payment usually stays REQUIRES_PAYMENT_METHOD. Before opening a new payment, check payments.get and the charge list. On hard decline, do not loop with the same card.
Backoff
const delays = [250, 750, 1500]; // ms, exampleMonitoring
- Consecutive failed confirm rate
- Webhook delivery failures
- Provider-level decline distribution (dashboard)