"code": "VALIDATION_ERROR",
"message": "Some fields are not valid.",
"request_id": "req_01J9…",
"details": { "expires_in": "Must be at least 900." }
code is stable. Branch on it.
message is for people and may be reworded. Never branch on it.
request_id names the request. Quote it to support.
| Status |
Code |
Meaning |
What to do |
| 401 |
INVALID_API_KEY |
Missing, wrong or revoked key, or outside its IP allowlist. |
Check the key. |
| 402 |
BALANCE_EXHAUSTED |
The balance cannot cover this Checkout. |
Recharge. |
| 403 |
PAIR_NOT_ALLOWED |
network or coin is outside the key’s Pairs. |
Fix the request. |
| 403 |
MERCHANT_SUSPENDED |
VoltPay suspended the account. |
Write to support. |
| 403 |
CHECKOUT_LIMIT_EXCEEDED |
The amount is above your limit, given in max_checkout_micro. |
Split the amount. |
| 404 |
CHECKOUT_NOT_FOUND |
No Checkout has that id in this Mode. |
Check the id and the key’s Mode. |
| 404 |
PAYMENT_NOT_FOUND |
No Payment has that id in this Mode. |
Same. |
| 409 |
REFERENCE_ALREADY_USED |
A Checkout with this reference exists. |
Read it with GET /v1/checkouts?reference=…. |
| 409 |
IDEMPOTENCY_KEY_REUSED |
The key was used with a different request. |
Use a new key. |
| 409 |
REQUEST_IN_PROGRESS |
The first request with this key is still running. |
Retry shortly, same key. |
| 409 |
CHECKOUT_NOT_OPEN |
The Checkout can no longer be cancelled. |
Read it. |
| 422 |
NO_ADDRESS_FOR_PAIR |
No Pair on offer has a Receive Address. Carries fix_url. |
Add an address. |
| 422 |
VALIDATION_ERROR |
A field is not valid. details says which. |
Fix the request. |
| 429 |
RATE_LIMITED |
Too many requests. |
Wait Retry-After seconds. |
| 500 |
INTERNAL |
An unexpected failure. |
Retry with the same Idempotency-Key. |
| 503 |
PAIR_AT_CAPACITY |
Every Tag Digit on the Pair is in use. |
Add Receive Addresses. |
| 503 |
PAIR_PAUSED |
VoltPay paused the Pair. |
Offer another Pair. |
| 503 |
TRY_AGAIN |
A time limit cut the request short. Nothing was committed. |
Retry after Retry-After. |
Send an Idempotency-Key on POST /v1/checkouts and on its cancel. A retry then returns the first answer.
POST /v1/checkouts HTTP/1.1
Authorization: Bearer gw_live_…
Idempotency-Key: order-1042-checkout
- Make one key for each operation and send the same key on every retry. At most 255 characters.
- Keys are remembered for 24 hours, with a fingerprint of the method, path and body.
| Situation |
Answer |
| Same key and same request, after the first finished |
The first answer again, with Idempotency-Replayed: true. |
| Same key, different body or path |
409 IDEMPOTENCY_KEY_REUSED. |
| Same key while the first still runs |
409 REQUEST_IN_PROGRESS. |
| The first request failed |
Nothing is remembered. The retry runs. |
503 TRY_AGAIN and 429 RATE_LIMITED: after Retry-After seconds.
- A timeout or a dropped connection: with the same key.
500 INTERNAL: only with the same key, because the work may have committed.
- Every
GET is safe to repeat.