Limits and versions
What the API accepts, how fast, and what we guarantee when the contract changes. The history of changes is in the changelog.
Limits
| What | Limit | Over it |
|---|---|---|
| File size | 14 MiB | 413 file_too_large |
| Pages in a PDF | 50 | 413 too_many_pages |
| Formats | PDF, JPEG, PNG, GIF, WebP | 415 unsupported_file_type |
| Submissions per key | 120 / min | 429 rate_limited, with Retry-After in seconds |
| Burst of submissions per key | 20 | the same |
| Documents read at once, per account | 2 | the rest wait in the queue, with no error |
Wait with mode=sync |
30 s | the answer is 202; carry on with GET or the webhook |
| Monthly usage (live keys) | the one in your contract | 402 quota_exceeded, until next month or until we raise it |
external_id |
128 characters | 400 invalid_request |
metadata |
20 keys, 500 characters each | 400 invalid_request |
buyer_name |
200 characters | 400 invalid_request |
limit on GET /v1/documents |
200 (default 50) | 400 invalid_request |
How long an Idempotency-Key is kept |
24 h | the same key is then a new request |
Sandbox keys have the same rate limit, but use nothing up and never get 402.
Webhooks. Your endpoint has 10 s to answer; a redirect is not followed but counted as a failure.
An event that is not delivered is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 8 h, 8 h (just over
24 h in all), then stops; ask for it again with POST /v1/documents/{id}/webhook. The signature
allows 5 minutes of difference from your clock.
Versions
The contract's version is a date, in the Fintray-Version header. The current version is 2026-10-19.
- A key stays on the version current when it was created. A request may name another supported
version in the
Fintray-Versionheader; one we do not serve gets400 unsupported_version. - Every response says, in the same header, which version it was built to.
- The
/v1prefix in the URL does not change with versions.
What we guarantee within a version
On your key's version we do not:
- remove or rename a field in a request, a response or an event;
- change the type or the meaning of a field, a confidence level or a code;
- make an optional request field required;
- change the HTTP status or the
error.codewe answer an existing situation with.
What may be added without a new version
Your integration should pass over what it does not know:
- new endpoints and new optional request fields;
- new fields in responses and events;
- new
warningscodes and new error codes; - new webhook event types: answer 2xx and ignore them.
The reading itself improves over time: a new model or rule may read the same file more correctly, so
values can differ from one submission to the next. What high, medium and low mean stays the same.
When a new version comes out
- We announce it by e-mail to each account's technical contact, with what changes and what you need to do, and record it in the changelog.
- Your key stays on the old version. Try the new one by sending
Fintray-Versionwith it, on your sandbox key first. When you are ready, we give you a new key, which is on the new version. - An old version is served for at least 12 months after the one replacing it comes out, and we announce the date it stops at least 90 days ahead.