Skip to main content
When something goes wrong, the response has an error message in plain words that you can show or log as it is:
A few endpoints add a field alongside it when there’s something useful to say. Validate a recipient returns valid: false with the error, and the scope errors below return a code. Read error first and treat anything else as a bonus.

Status codes

400: Bad request

  • amount needs to be a positive number rather than a string, zero, or a negative.
  • For POST /api/merchant/pay, amount runs from 0.01 to 10000.
  • Off-ramp and onramp amounts also have to be within the limits for the currency.

401: Unauthorized

Check the header reads Authorization: Bearer ms_live_..., and that the key is still active under API Keys. Wallet API calls use a wsk_live_ key instead.

403: Forbidden

Your key is fine, but the product you’re calling isn’t switched on for your account yet.
Email info@minisend.xyz and we’ll turn it on. See key scopes.

404: Not found

The session_id (which starts with cs_), order_id, wallet_id, or slug doesn’t match anything on your account. Orders and wallets that belong to someone else also show as 404, so nobody can find out they exist.

409: Conflict

The request is fine, but the order has already moved on. You’ll see this if you confirm a transfer for an automatic order (we spot those ourselves), for an order that’s already finished or expired, or with a transaction hash that’s already paid for a different order.

422: Unprocessable

The details were in the right format, but didn’t pass when we checked them. The two usual cases are a recipient account we couldn’t confirm, and a transfer that was too small or went to the wrong network or address. A 422 means nothing moved, so it’s safe to fix the details and call again.

429: Rate limit

Slow down and try again. The X-RateLimit-Remaining header tells you how many requests you have left. On top of the general limit per IP address, endpoints that move money have tighter limits per account, and onramp prompts are limited per phone number. See rate limits, and get in touch if you need more.

500 and 502: Our side

Try again, waiting a little longer each time. A 502 usually means we couldn’t reach a rate or a partner for a moment, and the next try will work. If either keeps happening, send us the session_id or order_id and we’ll look into it.

Handling errors

It’s safe to retry on 429, 500, and 502. On 400, 403, 409, and 422, sending the same request again will get the same answer, so fix something first.