Developers
Error codes
Every error code the uCrypto merchant API can answer with, its HTTP status and what it
means. Each error answer links to its code's entry here in its doc_url.
Every error answers with an error object holding its code, a
message, a doc_url and a request_id, and, when one
request field caused it, a param naming that field. The code
is safe to program against; the message is for people and may be reworded.
Codes are only ever added, never renamed or reused.
invalid_json
HTTP status 400
The request body is not valid JSON.
invalid_number
HTTP status 400
The body holds a number with a fraction or exponent, or one of 2^53 or more.
invalid_amount
HTTP status 400
An amount is missing or is not a whole number of minor units below 2^53.
invalid_parameter
HTTP status 400
A query parameter or body field, such as limit or unit, is not valid.
missing_idempotency_key
HTTP status 400
A POST, PUT, PATCH or DELETE call has no Idempotency-Key header.
invalid_idempotency_key
HTTP status 400
The Idempotency-Key is empty, too long or contains spaces.
missing_api_key
HTTP status 401
No Authorization: Bearer <key> header, or it is malformed.
invalid_api_key
HTTP status 401
The API key is unknown or has been revoked.
not_signed_in
HTTP status 401
A draft application call with no valid applicant session (see the application schema page).
sign_in_refused
HTTP status 401
A wrong, expired, used or locked applicant sign-in code; 403 if posted from another site.
insufficient_scope
HTTP status 403
The API key does not hold the scope this endpoint needs.
merchant_not_active
HTTP status 403
The key's merchant account is suspended or terminated.
api_key_wrong_mode
HTTP status 403
A sandbox key on an account that has gone live, or a live key on one that has not.
sandbox_only
HTTP status 403
A live key on an endpoint that works only in the sandbox, such as the event simulator.
https_required
HTTP status 403
The request arrived over plain HTTP; send it again over https. Nothing was read or done.
country_unknown
HTTP status 403
A purchase at /buy with neither a country of residence nor an IP country; nothing was charged.
not_found
HTTP status 404
There is no endpoint at that path, or no such item of yours (for example a redemption intent).
method_not_allowed
HTTP status 405
The path exists but not for that method; the Allow header lists methods.
idempotency_key_in_use
HTTP status 409
The first call with this key is still running; retry after Retry-After.
redemption_intent_not_open
HTTP status 409
The redemption intent has already been confirmed, cancelled or has expired.
redemption_not_reversible
HTTP status 409
The redemption cannot be reversed: not confirmed, already reversed by uCrypto, charged back, or more than your available balance.
api_key_in_use
HTTP status 409
A key cannot revoke itself: revoke it using another of your keys.
draft_out_of_date
HTTP status 409
A draft application save based on an older revision; newer answers were kept.
application_submitted
HTTP status 409
The application has been submitted, so it cannot be saved or submitted again.
section_not_reopened
HTTP status 409
The save changes a part of a re-opened application that staff did not re-open.
upload_failed
HTTP status 409
The document store did not receive the file; the message says what happened and the next step.
payload_too_large
HTTP status 413
The request body is over 64 KB.
idempotency_key_reused
HTTP status 422
The key was already used for a different request.
return_url_not_verified
HTTP status 422
The return_url is not an https:// address on your verified domain.
merchant_not_eligible
HTTP status 422
Your account is not approved, or serves no market that uses that unit.
currency_not_accepted
HTTP status 422
A redemption intent's unit is not one of the currencies your account accepts.
insufficient_balance
HTTP status 422
A payout is more than your available balance.
balance_in_settlement_hold
HTTP status 422
Part of a payout is still in the settlement hold.
bank_account_not_found
HTTP status 422
The bank account is not one of your verified bank accounts.
bank_account_blocked
HTTP status 422
Payouts to that bank account are stopped.
currency_mismatch
HTTP status 422
A payout's unit or bank account is not in your account's currency.
reversal_exceeds_redeemed
HTTP status 422
With earlier reversals, the amount is more than the customer paid with the intent.
webhook_event_too_old
HTTP status 422
The event is older than the replay window, so it cannot be replayed; nothing was queued.
rate_limited
HTTP status 429
Too many requests with this API key or applicant sign-in; retry after Retry-After seconds.
internal_error
HTTP status 500
Something failed on our side; quote the request ID.