Concepts

Errors

Every error has an HTTP status code and a JSON body with a slug you can branch on. Check the status code first, then the slug.

The error body

Attributes

statusstring: error
codestring: Short opaque token, stable across releases.
errorstring: Machine-readable slug. Mostly a fixed set; amount-range failures interpolate the limit, e.g. withdraw_amount_must_be_over_0.1_usd — match on the prefix.
request_idstring: Correlates with the server log line.

Branch on the status code

One endpoint, /api/user/info, puts your account's state in status instead of success. The HTTP status code is always right.

Example422 Unprocessable

{
  "status": "error",
  "code": "asd31",
  "error": "user_balance_low",
  "request_id": "1f8a0c2e4d6b8a0c2e4d6b8a0c2e4d6b"
}

Status codes

Status	Meaning	Retry
`400`Bad request	A parameter is missing or invalid, or no API key was sent.	No
`401`Unauthorized	The API key is malformed or unknown.	No
`403`Forbidden	Authenticated but not allowed, or the account is suspended.	No
`404`Not found	No object with that id, or no such endpoint.	No
`409`Conflict	The object is in the wrong state, or the same idempotency key is still running.	No
`413`Payload too large	The request body is over 256 KB.	No
`422`Unprocessable	Valid, but it cannot be done: balance too low, amount out of range.	No
`429`Too many requests	Wait for `Retry-After` seconds.	Yes
`500`Server error	Our bug. Quote the `request_id`.	Once
`503`Unavailable	A price feed or a node is down.	Yes

Grouped by status. Each entry is the error slug to branch on, then the older opaque code, which stays stable for integrations that already use it. Slugs with a {limit} carry the limit in the slug itself: match on the part before it.

400 Bad request

parameter_missingzOnNO: A required parameter is missing or empty. Also the answer when no API key is sent at all.
parameter_invalid0ne4r: A parameter is present but fails validation.
currency_not_foundwSjOp: The currency code does not exist, or has no usable rate.
invalid_recipient_addressadr01: The address fails the format or checksum of that currency. A cross-chain address is rejected.
invalid_idempotency_keyidm01: idempotency_key must be 1 to 128 letters, digits, - and _.

401 Unauthorized

key_or_user_not_foundkGodC: The API key is malformed or unknown.

403 Forbidden

not_permitted7UV9y: Authenticated, but the object belongs to someone else, or current_password was missing or wrong.
account_suspendedsus01: The key is valid but the account is suspended. Do not rotate the key; contact support.

404 Not found

uid_not_foundy1sDM: No transaction or withdrawal with that id.
uid_not_foundHjVwP: No seller with that id.
404AMbNc: No such endpoint.

405 Method not allowed

405mth01: The endpoint does not take that method. Every endpoint accepts GET and POST.

409 Conflict

payment_method_already_setaV9d9: A payment method was already chosen for this transaction.
transaction_inactiveaV9W9: The transaction is no longer pending.
transaction_already_completedaV9W9: The transaction has already completed.
username_takenH7qZW: Another account already uses that username.
already_claimedanV8l: That reward was already claimed.
request_in_progressidm02: A request with the same idempotency_key is still running.

413 Payload too large

413AMbNc: The request body is larger than 256 KB.

415 Unsupported media type

415ctp01: The request body type is not accepted. Send parameters form-encoded or in the query string.

422 Unprocessable

idempotency_key_reused_with_different_parametersidm03: That idempotency_key was already used for a request with different parameters.
requirements_not_metanV82: The reward's requirements are not met yet.
user_balance_lowasd31: Your withdrawable balance is too low.
amount_out_of_rangeasd31: The fees would consume the whole amount.
transaction_amount_must_be_over_{limit}_{currency}asd31: The transaction is worth less than the minimum. The slug names the limit, as in transaction_amount_must_be_over_0.1_usd; match on the prefix.
transaction_amount_must_be_under_{limit}_{currency}asd31: The transaction is worth more than the maximum. Match on the prefix.
withdraw_amount_must_be_over_{limit}_{currency}asd31: The withdrawal is below the minimum. Match on the prefix.
exchange_amount_must_be_over_{limit}_{currency}asd31: The exchange is below the minimum. Match on the prefix.
disabled_payment_methodwqtoJ: The seller has switched that payment method off.
payment_method_unavailable7NSza: The platform has paused or retired that payment method.
invalid_payment_methodteyKZ: That method is not allowed on this transaction, or is not on your account.
payouts_disabled_for_methodpay01: Payouts in that currency are switched off for now. Your balance is unaffected.
no_active_paypal_accountjYC4M: No PayPal account is enabled to receive the payment.
expiredanV8l: The reward's claim window has closed.

429 Too many requests

rate_limitedgba3C: Too many requests. Wait for the number of seconds in Retry-After.

500 Server error

server_errorn1RgP: A bug on our side. Quote the request_id to support.

503 Unavailable

service_unavailablesvc01: A dependency is down. Retry shortly.
rate_unavailablerat01: A price feed is stale, so the request is refused rather than priced off an old rate. Retry shortly.
node_unavailablekuJ0Q: The node for that currency is unreachable. Retry shortly.

Retrying

429 means wait. Retry after the number of seconds in Retry-After.
503 means a dependency is down. Retry with backoff; it usually clears within minutes.
500 is our bug. Retry once, then contact support with the request_id.
Any other 4xx means the request is wrong and will stay wrong. Fix it before you retry.
Send an idempotency_key on anything that moves money, so a retry can never act twice. See Idempotency.