API limits
Updated
The limits the API publishes, in one table. Each row has the value, what the API does at the limit and the docs section the limit comes from.
The rate limit is 600 a minute for each API key. A document has at most 200 pages, and an uploaded file is at most 25 MiB.
The values were read on . They come from the OpenAPI file, the server's code, its gateway configuration and the rate card. A test fails when a row here differs from the place it was read from. GET /v1/capabilities returns several of these limits for your key, so your code can read them and need not copy them.
The limits
| Limit | Value | At the limit, and its docs section |
|---|---|---|
| Requests | ||
| Rate limit: requests with one API key | 600 a minute | rate_limited (429). The RateLimit-Reset header says when the call can be repeated. Docs: Errors and states |
| Request body of a JSON call, unless the route has a larger limit | 1 MiB | payload_too_large (413). Send a smaller body. Docs: Errors and states |
Request body of POST /v1/documents | 4 MiB | payload_too_large (413). Send a smaller body. Docs: Errors and states |
| Request body of a POST to the MCP server | 4 MiB | request_too_large (413) from the MCP server, outside the error envelope. The gateway allows the same size on that host. Docs: Errors and states |
Length of an Idempotency-Key on a call with an API key | 255 characters | invalid_request (422). Use a shorter key. Docs: openapi.json |
Time an Idempotency-Key keeps replaying its answer | 24 hours | A replay is no longer promised. Use a new key for a new request. Docs: Full reference (no JS) |
Rows in one page of most lists, the limit parameter | 200 | invalid_request (422). A few lists take another maximum, and the OpenAPI file names each. Docs: openapi.json |
| Documents and quotes | ||
| Pages in one document | 200 | page_limit_exceeded (422). Nothing is stored or charged. Docs: Send a fax |
| Size of an uploaded PDF, PNG, JPEG or TIFF file | 25 MiB | payload_too_large (413). Upload a smaller file. Docs: Send a fax |
| Size of an HTML document | 2 MiB | payload_too_large (413). Send less HTML. Docs: Send a fax |
| Time to render an HTML document | 45 seconds | conversion_failed (422). Make the document smaller and create it again. Docs: Send a fax |
| Pixels in one image frame | 50 million | image_too_large (422). Make the image smaller and create the document again. Docs: Send a fax |
| Image frame printed without scaling | 2550 by 3300 pixels | A larger frame is scaled down to fit. The document carries the image_downsampled warning. Docs: Send a fax |
Length of sender_name on a quote | 128 characters | invalid_request (422). details names the field. Docs: Send a fax |
| Life of a quote | 10 minutes | quote_expired (409). Quote again. Docs: Send a fax |
| Life of a signed download URL | 10 minutes | The URL stops working. Call the download route again for a new one. Docs: Receive a fax |
| Days a document is kept, by default | 30 days | The document is no longer kept. A read answers document_expired (410) until the bytes are removed. Docs: Receive a fax |
| Days a received fax is kept, by default | 90 days | The received fax is no longer kept. A read answers inbox_item_expired (410) until the bytes are removed. Docs: Receive a fax |
| Faxes | ||
| Attempts in all for one fax, when the line is busy or does not answer | 3 | No further attempt is made. The fax ends failed and nothing is charged. Docs: Send a fax |
| Webhooks, keys and approvals | ||
| Age of a webhook timestamp your handler should accept | 300 seconds | Your handler rejects the request. This check runs in your code, not on our side. Docs: Webhooks |
| Delivery attempts for one webhook event | 6 | No further attempt is made. POST /v1/webhook-deliveries/{id}/replay sends the event again. Docs: Webhooks |
| Time the old webhook secret keeps signing after a rotation | 24 hours | The old secret stops signing. Deliveries then carry the new signature only. Docs: Webhooks |
| Longest time the old API key secret keeps working after a rotation | 24 hours | The old secret stops working. It stops sooner if its own expiry is earlier. Use the new one. Docs: Agents |
| Age of the sign-in that can approve a request | 15 minutes | step_up_required (403). The person confirms with a passkey or a fresh magic link. Docs: Approvals |
| Life of a sandbox scenario | 24 hours | The scenario ends. Select it again to keep it. Docs: Sandbox |
| One-time send | ||
| Document pages in one order | 20 | too_many_pages (422). Use the prepaid wallet for a longer document. Docs: One fax by card |
| Size of the file of one order | 10 MiB | document_too_large (422). Use the prepaid wallet for a larger file. Docs: One fax by card |
Length of sender_name on an order | 2 to 120 characters | invalid_request (422). details names the field. Docs: One fax by card |
| Shortest time an unpaid order is kept | 48 hours | The order expires once no checkout is open. Nothing was charged. Docs: One fax by card |
| Time the confirm link works after the payment | 48 hours | The order expires. The authorization is given back and nothing is charged. Docs: One fax by card |
| Life of a status token | 7 days | The token stops working. Docs: One fax by card |
| Time without a report from the carrier | 48 hours | The authorization is given back and nothing is charged. Docs: One fax by card |
What your code should do at a limit
A refusal in the table is the same envelope as every other error. Its retryable field says whether the same call can be tried again. The errors page has the action for each code.
After rate_limited, wait and send the call again with the same Idempotency-Key. The other refusals mean the request has to change before you send it again: a smaller body, fewer pages or a new quote.
What the table leaves out
- The longest value of each field, such as a label or a webhook URL. openapi.json has it as the
maxLengthof the field. - Limits you set yourself. A delegated policy caps what an agent can send, and a budget caps what it can spend.
- Amounts of money. The pricing page has the prices and the smallest and largest top-up.
- The daily limits of a one-time send, per email address, per destination number and per network address. Their values are not published. Over one, the create answers 429
rate_limitedanddetails.capnames the limit. See the one-time send limits.