API rate limits and 429 errors

The limit

Each API key may make 300 requests per minute, counted in fixed one-minute windows. Every authenticated response includes three headers:

Over the limit, the API returns 429 with code rate_limited and a Retry-After header: the number of seconds to wait.

Waiting and retrying

Read Retry-After, wait that long, then send the same request again. For a POST, keep the same Idempotency-Key so the retry can't do anything twice.

async function signwith(url, options = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch(url, {
      ...options,
      headers: { Authorization: `Bearer ${process.env.SIGNWITH_API_KEY}`, ...options.headers },
    })
    if (response.status !== 429) return response
    const seconds = Number(response.headers.get('Retry-After')) || 60
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
  }
  throw new Error('Still rate limited after 5 attempts')
}

If you send documents in bulk, watch RateLimit-Remaining and slow down before it reaches zero.

Other limits

Two endpoints have their own limits on top of the per-minute one:

• Reminders: POST /signature_requests/{id}/remind works at most once an hour per signature request. Sooner, it returns 429 remind_too_soon, with Retry-After set to the seconds left.
• Resending one signer's link: PATCH /signers/{id} with resend: true emails a signer at most once every 10 minutes. Sooner, it returns 429 remind_too_soon with Retry-After.
• Feedback: POST /feedback accepts 20 messages per user per clock hour, then returns 429 rate_limited with Retry-After set to the seconds until the next hour.

Webhooks don't count against your limit: SignWith calls you. Using webhooks instead of polling is the easiest way to stay well under it. See webhooks.