Status codes
The error body
Error responses follow RFC 7807.
Every error body carries
correlation_id, and repeats it as request_id. Log correlation_id on every failure. Quote it along with your reference when you contact support, because together they locate the request without a search.
If 5xx errors or timeouts persist across retries, check status.bitnob.com for an ongoing incident before contacting support.
Rate limits
The API allows 500 requests per minute from each IP address. Every response carriesX-Ratelimit-Limit, X-Ratelimit-Remaining, and X-Ratelimit-Reset, so you can see how close you are before you’re throttled. A request over the limit returns 429: back off exponentially and retry after the reset. Design batch jobs to pace themselves rather than racing the limiter; see Send payouts in bulk for the pattern.
The retry discipline
Money movement makes naive retries dangerous, and one habit removes the danger:1
One reference per business action
Generate a unique
reference per payout, transfer, trade, or card operation, before the first attempt, and persist it with the intent.2
Retry with the same reference
On timeout or
5xx, re-submit the identical request. For most endpoints, if the original succeeded you get its result back or a 409, and nothing executes twice. Crypto-pair trades are the exception: the reference isn’t checked there, so look the order up before you resend. Either way, a timeout is never a reason to mint a new reference.3
Treat 409 as an answer, not an error
A duplicate-reference conflict means the action already exists. Fetch it by reference and continue as success.
4
Confirm outcomes from webhooks
The synchronous response says “accepted”, the webhook says “done”. Reconcile on a schedule against the relevant list endpoint so a missed delivery cannot strand a record. See Webhooks and event handling.
Backoff that behaves
- Exponential with jitter: 1s, 2s, 4s, 8s, capped.
- Bounded attempts, then a human: pages that alert your ops channel beat infinite loops.
- No retry storms: when everything fails at once, the cause is systemic; hammering makes it worse.
- Never blind-retry a failed (as opposed to timed-out) money movement; read the failure reason first, because some causes, like compliance blocks, do not resolve by retrying.