Best practices

Idempotency

Include X-Idempotency-Key on POST/PUT/PATCH to prevent duplicates during retries.

Retry with backoff

async function retry(fn, max = 3) {
  for (let i = 0; i <= max; i++) {
    try { return await fn(); }
    catch (e) { if (i === max || !e.retryable) throw e;
      await new Promise(r => setTimeout(r, 1000 * 2 ** i + Math.random() * 500)); }
  }
}

Webhook security

• Verify HMAC-SHA256 signature before processing
• Use timing-safe comparison
• Check timestamp within 5 minutes (replay prevention)
• Return 200 quickly, process async

Pagination

List endpoints return paginated results. Always iterate through all pages using page and per_page params.