Docs › Build with Beluga

Errors & retries

What the API answers when something is wrong, and which calls are safe to repeat.

Errors

Every error is JSON {"error": "message"} with a 4xx or 5xx status. Messages are for humans; branch on the status code.

Status	When	Example message
`400`	Invalid input or malformed JSON	`hlAddress must be 0x + 40 hex`, `amount must be 0.00132–5 BTC (minimum $100)`, `supported: BTC>XMR, XMR>BTC`, `bad request`
`404`	Unknown order ID or path	`not found`
`429`	Rate limit reached	`rate limit`
`503`	No reliable price right now	`price source unavailable`, `price sources disagree, try again shortly`

Wagyu comparison quotes never fail the request: they come back as {"pending": true} or {"error": "…"} inside the wagyu field.

All GET endpoints are safe to repeat. Retry 429, 503 and network errors with backoff (for example 2 s, 5 s, 15 s).
POST /api/deposit and POST /api/withdraw are not idempotent. Each successful call creates a new order. If a call times out without an answer, create a new order and fund only one you received an id for; unused orders simply expire.
Never retry a 400 without changing the input.
Pending Wagyu quote: call GET /api/quote/wagyu with the same parameters; it waits for the answer.

Send each deposit once. A second transfer to the same subaddress adds to the same order.
Don't resend XMR2 because a redemption shows awaiting_tokens for a few seconds: transfers are picked up within about 20 seconds.
If funds were sent to an expired or wrong order, see Late deposits & recovery.