Error codes

Error format

Every error has ok set to false and the details in error:

403 Error

{
    "ok": false,
    "error": {
        "code": "pin_blocked",
        "message": "This PIN is blocked",
        "fields": null
    }
}

422 Some fields are missing or invalid

{
    "ok": false,
    "error": {
        "code": "validation_error",
        "message": "The amount field is required.",
        "fields": {
            "amount": [
                "The amount field is required."
            ]
        }
    }
}

error.code

Stable, machine-readable identifier. Codes are never renamed or reused, so it is safe to branch on them.

error.message

Human-readable explanation in your account language. It can change at any time; show it or log it, but never use it in your logic.

error.fields

For problems with what you sent, an object with each failing field and its messages. Otherwise null.

HTTP status codes

200 OK

The request worked.

401 Unauthorized

The request could not be authenticated: missing headers, a bad signature, a stale timestamp, a reused nonce or an unknown key.

402 Payment required

A wallet or PIN does not hold enough value for the operation.

403 Forbidden

Authenticated, but not allowed: IP not whitelisted, Idempotency-Key problems, a permission that is off for your account, or a PIN in the wrong state.

404 Not found

The PIN, product, location or webhook does not exist for your account in this mode.

409 Conflict

The PIN is already in the state you asked for.

422 Unprocessable

A field failed validation, or an amount is outside what the product allows.

429 Too many requests

More than 60 requests in a minute, or a write sent while another write for your account was still running.

500 Server error

Something went wrong on our side. These are rare; retry later, and contact support if it persists.

The 60-per-minute limit is enforced before your request reaches the API, so that 429 response has no code. Treat any 429 as "slow down and retry".

Handling errors

Branch on code. Each reference page lists the codes its endpoint can return.
4xx errors will fail again if you resend the same request; fix the request first. The exceptions are rate_limited and a 429 without a code, which you can retry after a short wait.
On a 500 or a timeout, you do not know whether a write went through. Retry with the same external_reference and a new Idempotency-Key: if the first attempt succeeded you get duplicate_external_reference instead of a duplicate.
Some codes use a different HTTP status on some endpoints for the same condition, for example invalid_webhook_id is 422 when issuing a PIN and 404 elsewhere. The status below is the default; reference pages show the status each endpoint actually returns.

Signing and access

401 missing_auth_headers Sign the request: X-Key-Id, X-Timestamp, X-Nonce and X-Signature are all required

401 timestamp_out_of_window X-Timestamp is more than 5 minutes away from our clock

401 invalid_signature The signature does not match the request

401 nonce_replayed This X-Nonce has been used already; send a new one with every request

401 invalid_api_key This API key is unknown, revoked or expired, or live access is not switched on

403 ip_not_allowed Requests from this IP address are not on the key's allow-list

403 idempotency_key_required Send an Idempotency-Key header with every request

403 idempotency_key_too_long Idempotency-Key can be at most 50 characters

403 idempotency_key_reused This Idempotency-Key has been used already

403 wrong_account_type Your account type cannot use this endpoint

Any endpoint

422 validation_error Some fields are missing or invalid

422 duplicate_external_reference You have sent this external_reference before

403 currency_not_supported Your account has no wallet in this currency

429 rate_limited Too many requests. Wait a moment and try again

500 internal_error Something went wrong on our side. Try again; if it keeps happening, contact support

What the account may do

403 issuing_disabled Issuing PINs is not switched on for your account. Contact support

403 redeeming_disabled Redeeming PINs is not switched on for your account. Contact support

403 cashout_unavailable Cashouts are not available yet

Products

404 catalog_item_not_found No item in your catalog has this catalog_id

403 product_inactive This product is switched off

403 pin_type_inactive This PIN type is paused

403 pin_not_accepted_here Your account does not accept this PIN type

PIN codes

422 pin_checksum_failed This is not a valid PIN code: its check digit is wrong

404 pin_code_unknown No PIN has this code

403 pin_code_replaced This code has been replaced by a newer one; ask the customer for their latest code

404 test_pin_unknown Test keys only accept the test PINs listed in the docs

404 pin_not_found No PIN has this id

403 pin_sold_elsewhere This PIN was not sold by your account

500 pin_generation_failed A new PIN code could not be created. Try again

PIN state

403 pin_blocked This PIN is blocked

403 pin_expired This PIN has expired

409 pin_already_active This PIN is already active

409 pin_already_blocked This PIN is already blocked

Amounts and balances

402 wallet_balance_low Your wallet balance does not cover this amount

402 pin_balance_low The PIN's balance does not cover this amount

403 full_balance_required This PIN is single use: the amount must be its whole balance

403 pin_daily_limit_reached This PIN has a daily spending limit, and this amount is over what is left of it today

403 family_cards_not_allowed This card can't have family cards

403 pin_frozen The PIN's holder has frozen it. They can unfreeze it from their card account

403 pin_cashout_blocked This PIN was topped up by its holder's card payment, so it can't be cashed out

422 amount_too_small The amount is below this product's minimum

422 amount_too_large The amount is above this product's maximum

422 amount_not_offered This product is only sold in set amounts, and this is not one of them

422 keep_code_not_allowed This product does not let customers keep the same code (allow_keep_code in the catalog)

422 daily_limit_not_allowed This product is spent in one go, so a PIN of it cannot have a daily limit

422 terminal_daily_limit This terminal has reached its daily limit

Top-ups and cashouts

403 topup_not_allowed This PIN type cannot be topped up

403 fee_wallet_missing The platform fee wallet for this currency is not set up

Printed cards

403 physical_vouchers_not_permitted Printed cards are not switched on for your account. Contact support

403 physical_vouchers_unavailable This product cannot be ordered as printed cards

404 physical_voucher_not_found No printed card has this number

409 physical_voucher_not_shipped This card's order has not shipped yet

409 physical_voucher_already_activated This card has already been activated

409 physical_voucher_void This card has been cancelled

403 physical_voucher_live_only Printed cards can only be activated on a live terminal

Records the request points to

404 transaction_not_found No transaction of yours has this reference

404 invalid_webhook_id No webhook of yours has this webhook_id

422 invalid_store_id No store of yours has this store_id

422 invalid_terminal_id No terminal of yours has this terminal_id

403 terminal_disabled This terminal is switched off

422 terminal_store_mismatch This terminal_id belongs to a different store than store_id

429 reissue_limit_reached This PIN's code has been reissued too many times today. Try again tomorrow

Quotes

404 quote_not_found No quote of yours has this id or reference

409 quote_not_cancellable This quote has been paid or withdrawn already, so it cannot be withdrawn

422 quote_discount_too_high The discount is above what resellers earn on this product (max_quote_discount in your issuing catalog)

Wallet passes

503 wallet_unavailable Wallet passes are not available right now. Try again later

Store addresses

404 purchase_location_not_found No store of yours has this id

404 redemption_location_not_found No store of yours has this id

422 invalid_country_iso2 country must be a two-letter ISO code we know

422 invalid_state_iso2 state must be the ISO code of a state in that country

422 invalid_postal_code postal_code is not in that country's format