Errors & rate limits

How Merchant API reports failures and how throttling works.

Error shape

Errors typically look like:

{
  "success": false,
  "message": "Human-readable summary",
  "error_type": "insufficient_scope",
  "data": {}
}

Auth & access

invalid_api_key — 401
merchant_api_disabled — 403
kyb_not_complete — 403 (live key before business KYB complete)
ip_not_allowed — 403
insufficient_scope — 403

Customers / KYB

kyb_incomplete — 422 on submit; data.missing lists gaps
invalid_status_transition — 422 when submit/update is not allowed
invalid_document_type — 422

Rate limits

Bearer Merchant routes are throttled at 120 requests / minute per API credential. When exceeded, expect HTTP 429. Back off and retry with jitter.

Webhook delivery failures

If your receiver does not return 2xx, Bitstac retries with backoff (1m, 5m, 30m, 2h, 12h) until max retries. Inspect deliveries in Developers → Webhooks. See Webhooks.