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. |
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). |
Common validation messages#
Amount must be between 0.01 and 10000 with at most two decimal placesInvalid payout wallet: use a non-zero Polygon address with a valid checksumTotal 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 |
| 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.