API Reference

Errors & Rate Limits

HTTP status codes, error bodies and how to handle them.

Error format#

Errors return a JSON body with a human-readable error. When your code can react to the problem, a machine-readable code is included as well.

{
  "error": "Provider \"moonpay\" requires at least 30 USD. Got 10 USD.",
  "code":  "below_minimum"
}

HTTP status codes#

Status	Meaning	What to do
`400`	Invalid request: missing field, bad wallet, amount out of range, provider problem.	Read `error` / `code`, fix the input. Do not retry unchanged.
`401`	Missing, invalid or revoked API key.	Check the header or create a new key.
`403`	The feature is not enabled for your account.	Contact support.
`404`	Payment not found, or it belongs to another account.	Check `payment_id` / `ipn_token`.
`429`	Rate limit reached.	Wait for `Retry-After` seconds.
`500`	Unexpected server error.	Retry with exponential backoff.
`502`	The on-ramp provider is temporarily unavailable.	Retry later or use `multi`.
`503`	Crypto only: no current price for the coin.	Retry after a few seconds or offer another coin.

Error codes#

code	Meaning
`below_minimum`	The amount is below the provider's minimum. Increase it or use `multi`.
`currency_locked`	The provider only supports one currency, see restrictions.
`provider_unknown`	The provider ID does not exist.
`provider_inactive`	The provider is currently not available.
`conversion_failed`	The amount could not be converted to USD. Try again shortly.
`provider_unavailable`	The provider did not respond (HTTP 502).
`validation_error`	Crypto API: a parameter is missing or invalid; `error` names it.
`invalid_coin`	The coin is unknown, see supported coins.
`invalid_address`	The payout address does not fit the selected network.
`crypto_disabled`	Direct crypto is not enabled for your account (HTTP 403).
`payout_address_not_approved`	The payout address is not an approved payout wallet (HTTP 403).
`quote_unavailable`	No current price for the coin (HTTP 503).
`too_many_open_payments`	Crypto API: 100 payments of your account are already inside their 60-minute window (HTTP 429).
`invalid_api_key / rate_limited / not_found`	Crypto API: HTTP 401, 429 and 404.

Common validation messages#

Amount must be between 0.01 and 10000 with at most two decimal places
Invalid payout wallet: use a non-zero Polygon address with a valid checksum
Total amount including fees must not exceed 10000 (with fee pass-through)
Provide ipn_token or payment_id (Payment Status)

Rate limits#

Endpoint	Limit
`POST /api/v1/wallet`	60 requests / minute / API key
`GET /api/v1/payment-status`	120 requests / minute / API key
`POST /api/v1/crypto/payments`	60 requests / minute / API key
`GET /api/v1/crypto/payments/{id}`	120 requests / minute / API key
`GET /api/v1/crypto/currencies, /crypto/quote`	60 requests / minute / API key
Crypto create and quote, all keys of one account	60 requests / minute each
Requests without a valid key	30 requests / minute / IP

Over the limit you get 429 and a Retry-After header in seconds. Back off with some random jitter so that parallel workers do not retry at the same time.