Crypto payment API errors, rate limits and safe retries

There is no envelope. A validation failure is { "error": "Validation failed", "details": { ... } }; everything else is { "error": "Human-readable message" }, often with a machine-readable code and context. Match on the status code first and on code where present, never on the text.

A 429 includes standard rate-limit headers. Limits are shared across gateway replicas.

Retry only 429, 502 and 503, with jittered exponential backoff. The request function signs afresh on every call; a withdrawal's Idempotency-Key is generated once, stored with your payout record, and reused on every attempt, so a network-level retry can never pay twice.

async function withRetry(makeRequest, { attempts = 5 } = {}) {
  for (let i = 0; i < attempts; i++) {
    const res = await makeRequest();          // makeRequest signs afresh each time: new timestamp, new signature
    if (res.status < 400) return res;
    const retryable = res.status === 429 || res.status === 502 || res.status === 503;
    if (!retryable || i === attempts - 1) return res;   // 4xx is an answer, not an outage: do not retry it
    await new Promise((r) => setTimeout(r, Math.min(30000, 500 * 2 ** i) * (0.5 + Math.random() / 2)));
  }
}

// A withdrawal keeps the SAME Idempotency-Key on every attempt:
const key = 'wd_2026_10_10_0001';   // generated once, stored with your payout record
await withRetry(() => call('POST', '/v1/withdrawals', body, { 'Idempotency-Key': key }));

• A timeout is not a failure. The request may have succeeded; retry with the same idempotency key, or read the resource.
• Don't retry a 4xx. On invoice creation a 4xx is a real refusal, not a transient fault.
• A gas shortfall on a withdrawal is not an API error: the request succeeds as processing. Watch withdrawal.status_changed or poll GET /v1/withdrawals/:id.