Skip to content

Errors and retries

{
"error": {
"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.