Polling too fast

One API key read one document more often than it changes.

Problem type	`/problems/polling-too-fast`
HTTP status	429
Emitted by	REST API (/v1)
Title values	`This document is being read too often`
Extra members	`events_urlpoll_interval_sretry_after_swebhooks_url`
Response headers	`LinkRetry-AfterX-SignEnvoy-Poll-Interval`
Trigger	REST API (/v1): D155 (ADR 0053): one API key read one document more than 10 times at once, then faster than once every 15 s. Carries `Retry-After`, `retry_after_s`, `poll_interval_s`, `webhooks_url`, `events_url` and the `X-SignEnvoy-Poll-Interval` header

What happened

The response is HTTP 429 with a Retry-After header in seconds. One API key read the same document more than 10 times in a burst, and then faster than once every 15 seconds. The problem body carries retry_after_s, poll_interval_s (the interval we recommend, 30), webhooks_url and events_url.

What it means

Only that document, for that key, was refused. Other documents, other keys and every other operation carry on. The workspace’s fair-use limit (rate-limited) is separate.

A document only changes when someone signs, declines or opens it, or when the sealed PDF is ready. Reading it every few seconds mostly returns the same thing.

What to do next

Subscribe a webhook to document.completed and document.sealed (and document.signed if you show progress), and read the document once when the event arrives. On localhost, senv webhook tail --forward http://localhost:3000/webhooks/signenvoy --secret YOUR_LOCAL_SECRET delivers the same events without a tunnel.

If you have to poll, wait Retry-After seconds, then read every 30 seconds. Send the ETag from your last read as If-None-Match: an unchanged document answers 304 with no body. Or add ?wait=30 and the request returns as soon as the document changes. Polling and webhooks has the details.

Problem body

Every error the API returns is an RFC 9457 problem document with media type application/problem+json. The type member is the stable identifier to switch on; docs_url is this page.

{
  "type": "/problems/polling-too-fast",
  "title": "This document is being read too often",
  "status": 429,
  "instance": "/v1/...",
  "docs_url": "https://staging.signenvoy-docs-b4g.pages.dev/errors/polling-too-fast",
  "events_url": "...",
  "poll_interval_s": "...",
  "retry_after_s": "...",
  "webhooks_url": "..."
}