Vouchereto API · v1
Error codes
Errors are application/problem+json with a stable code. Branch on the code, not on the message, and log request_id. Unexpected server errors return 500: retry with the same idempotency key.
HTTP 400
VALIDATION_ERROR
The body or a query parameter is invalid. detail lists each failing field.
What to do: Fix the request. Unknown fields are rejected too (bodies are strict). Do not retry
IDEMPOTENCY_KEY_REQUIRED
A POST arrived without an Idempotency-Key header.
What to do: Send a unique key per logical operation (for example your order id) and reuse it on retries. Do not retry
HTTP 401
UNAUTHENTICATED
Missing, malformed, revoked or unknown API key.
What to do: Send Authorization: Bearer vch_test_… / vch_live_… exactly as shown when the key was created. Do not retry
INVALID_SIGNATURE
Vouchereto-Signature is missing or wrong. detail is MALFORMED, TIMESTAMP_OUT_OF_RANGE (clock skew over 300 s) or MISMATCH.
What to do: Sign t + "." + METHOD + " " + path_with_query + "\n" + raw_body with the key secret, include /v1 in the path, sign GETs with an empty body, and send the exact bytes you signed. Keep your clock in sync (NTP). Do not retry
HTTP 403
FORBIDDEN
The key cannot act on this resource.
What to do: Use a key of the merchant that owns the resource. Do not retry
MERCHANT_NOT_ACTIVE
Your merchant account is not enabled for this mode: still onboarding, suspended, or a live key before go-live.
What to do: Use a test key until your account is live. Contact support if you were suspended. Do not retry
LIVEMODE_NOT_ALLOWED
A live key called a sandbox-only endpoint (/v1/sandbox/*).
What to do: Use a vch_test_ key. Do not retry
HTTP 404
NOT_FOUND
The resource does not exist.
What to do: Check the id and the mode: test and live objects are invisible to each other. Do not retry
VOUCHER_INVALID
No voucher matches this code for your merchant (typo, wrong mode, or a merchant voucher for another merchant).
What to do: Ask the customer to check the code. Repeated failures block the customer for a while (TOO_MANY_INVALID_ATTEMPTS). Do not retry
REDEMPTION_NOT_FOUND
No redemption with this id for your merchant in this mode.
What to do: Check the id and that you use a key of the same mode. Do not retry
SESSION_NOT_FOUND
No checkout session with this id for your merchant in this mode.
What to do: Check the id and the key mode. Do not retry
HTTP 409
VOUCHER_RESERVED
The voucher is already reserved by another redemption.
What to do: Wait for that reservation to be captured, cancelled or to expire. Do not retry in a loop. Retry later (respect Retry-After when present)
VOUCHER_ALREADY_REDEEMED
The voucher was already used. Vouchers are single-use.
What to do: Tell the customer the code has been used. Do not retry
REDEMPTION_NOT_CAPTURABLE
Only reserved redemptions can be captured or cancelled; this one is cancelled or expired.
What to do: Reserve again if the customer still wants to pay. Do not retry
REDEMPTION_ALREADY_CAPTURED
The redemption was already captured (captures are final).
What to do: Treat it as success. Cancelling a capture is not possible. Do not retry
IDEMPOTENCY_CONFLICT
This Idempotency-Key was already used with a different request body.
What to do: Use a new key for a different operation; reuse a key only to retry the identical request. Do not retry
IDEMPOTENCY_IN_PROGRESS
A request with the same key is still being processed.
What to do: Retry the same request after a short wait (in-progress keys are released after 2 minutes). Retry later (respect Retry-After when present)
HTTP 422
VOUCHER_EXPIRED
The voucher is past its expiry date.
What to do: Tell the customer the voucher expired. Do not retry
CURRENCY_MISMATCH
The voucher is in a different currency than the one you sent.
What to do: Send the voucher's currency, or tell the customer it cannot be used here. Do not retry
CURRENCY_NOT_ACCEPTED
Your merchant account does not accept this currency (or has no checkout product in it).
What to do: Use a currency enabled for your account, or ask us to add one. Do not retry
UNIVERSAL_NOT_ACCEPTED
A universal voucher was presented but your account accepts only your own merchant vouchers.
What to do: Tell the customer, or ask us to enable universal vouchers. Do not retry
AMOUNT_OUT_OF_RANGE
The checkout amount is outside your configured minimum/maximum.
What to do: Send an amount inside your range (shown in the merchant portal). Do not retry
COUNTRY_NOT_ALLOWED
Your merchant category cannot sell to the country you sent.
What to do: Do not offer vouchers to customers in that country. Do not retry
PSP_PROGRAM_NOT_APPROVED
Card payments for your merchant category are not approved yet for this country.
What to do: Contact support; nothing to change in your request. Do not retry
STATE_INVALID
The requested state is not valid (for example an unknown sandbox voucher state).
What to do: Use one of the documented values. Do not retry
HTTP 429
RATE_LIMITED
Too many requests for this key (or too many failed authentications from your IP).
What to do: Wait Retry-After seconds, then retry with backoff. Retry later (respect Retry-After when present)
TOO_MANY_INVALID_ATTEMPTS
Too many invalid codes for this customer, customer IP or merchant. Blocks start at 5 minutes and grow up to 24 hours.
What to do: Show the customer a "try again later" message. Send X-Customer-Ip so one customer cannot block others. Retry later (respect Retry-After when present)
HTTP 500
INTERNAL
Something failed on our side. Nothing was half-applied: money movements are transactional.
What to do: Retry with the same Idempotency-Key and backoff. If it persists, send us the request_id. Retry with the same Idempotency-Key