Reference

Errors & rate limits

Blockcade uses conventional HTTP status codes. Every error response is JSON with a stable machine-readable type.

Error shape

{
  "error": {
    "type":    "invalid_request",
    "message": "amount must be greater than 0.",
    "param":   "amount"
  }
}

HTTP status codes

Code	Meaning	What to do
200	Success	Continue.
201	Resource created	Read the response body for the new object.
400	Invalid request	Check the `message` and `param` field. Do not retry unchanged.
401	Missing or invalid API key	Check your `Authorization` header.
403	Forbidden	Wrong environment (test key on live endpoint) or unverified merchant.
404	Not found	The resource doesn't exist or belongs to another merchant.
409	Conflict	Session is not in the expected state (e.g. already paid).
429	Rate limited	Back off. Respect `Retry-After` header.
500	Server error	Retry with exponential backoff.
502/503	Upstream provider unavailable	Retry with exponential backoff.

Common error types

error.type	When
invalid_request	Missing or malformed field. `param` tells you which one.
authentication_required	No API key, wrong header format, or key revoked.
rate_limited	Hit your per-key rate limit.
not_found	Reference doesn't exist under this account.
invalid_state	Session isn't in a state that allows the action (e.g. cancelling a paid session).
provider_error	Underlying payment provider (CoinGate/Alchemy Pay) rejected the request.

Rate limits

Test mode

25 req/sec

Per API key.

Live mode

100 req/sec

Per API key. Higher tiers on request.

Handling 429

async function withRetry(fn, maxRetries = 4) {
  for (let i = 0; i <= maxRetries; i++) {
    try { return await fn(); }
    catch (err) {
      if (err.status !== 429 || i === maxRetries) throw err;
      const wait = 1000 * Math.pow(2, i);   // 1s, 2s, 4s, 8s
      await new Promise(r => setTimeout(r, wait));
    }
  }
}

Debugging

Failed calls show up in Dashboard → API keys → recent requests (coming soon).
Webhook failures show up in Dashboard → Deliveries with the full response body from your endpoint.
For anything unexplained, email support@blockcade.app with your reference or delivery_id.