Limits
The size, count and requests-per-second limits of the API.
Every limit of the API in one place. The values on the other pages of these docs come from this same list.
| Limit | Value |
|---|---|
| PDF size, by URL or two-step upload | 10 MB |
| PDF size, in multipart/form-data | 4 MB |
| PDF size, in base64 (once decoded) | 3 MB |
| Request body | 4.5 MB |
| Lifetime of an upload’s upload_url | 2 hours |
| Time to use an upload in a letter | 24 hours |
| Sheets per letter, counting the one the address sometimes adds | 6 sheets |
| Wait for the document.url download | 10 seconds |
| PDF variables per letter | 100 variables |
| PDF variable name | 60 characters |
| PDF variable value, on one line | 500 characters |
| Keys in metadata | 20 keys |
| Metadata key name | 40 characters |
| Metadata value | 500 characters |
| reference | 100 characters |
| Idempotency-Key | 255 characters |
| Idempotency-Key lifetime | 24 hours |
| Requests per second, per account | 50 per second |
| Items per page when listing | 100 items |
| Events kept | 30 days |
| PDF available at preview_url, at least | 90 days |
| Scheduling with send_date, at most | 180 days ahead |
| Wrong codes per verification | 5 attempts |
| Time to confirm the code, after posting | 60 days |
| Time to share the location on the page, after confirming | 30 minutes |
| Time for your webhook to answer | 15 seconds |
Requests per second
Each account can make up to 50 requests per second. The limit applies to the whole account, across all of its keys.
Every response carries headers with the state of the limit:
| Header | What it is |
|---|---|
RateLimit-Limit | How many requests per second the account can make. |
RateLimit-Remaining | How many more fit in the current second. |
RateLimit-Reset | In how many seconds the count starts over. |
When the account goes over the limit, the API answers 429 with rate_limit_exceeded and a Retry-After header with the seconds to wait. Nothing is created. Wait that long and retry with the same Idempotency-Key.
HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1File sizes
A request body can be up to 4.5 MB. That is why a PDF sent inside the request can be up to 4 MB in multipart/form-data and up to 3 MB in base64. By URL or with the two-step upload (POST /v1/uploads), the PDF can be up to 10 MB. See Document and address area.
Large sends
To send thousands of letters, such as a month of invoices:
- Check the cost first. Price a typical letter with
POST /v1/letters/quoteand compare the total with your balance fromGET /v1/balance. A letter sent right away is only created when the balance covers its price. - Use a queue with a few parallel workers. Put each letter on a queue and consume it with a few workers, 5 to 10. That stays well under the limit and leaves room for your system's other calls.
- Give each letter its own
Idempotency-Key, such as the invoice id. If part of the run fails and you run it again, letters already created are not repeated. See Idempotency. - Treat a 429 as a signal to slow down. Respect
Retry-Afterbefore going on. - Follow the results with webhooks, not by retrieving each letter. See Webhooks.
If you already know the date of a large send, schedule it with send_date: the letters are validated and ready, and the balance only has to cover the total on the send date.
Need more
If your volume needs a higher limit, contact CartaFlow from the dashboard.