Limits
Rate limits, quotas, file sizes, pages and formats.
On this page
The figures below are ReceViz's defaults. ReceViz can set other limits for an organization, and you can set tighter ones on a key; where that is so, the page says.
Rate limits#
Requests are counted per credential, in one-minute windows. A client token counts against the key that minted it, so everything a key's tokens send shares the key's limit.
| Credential | Requests a minute |
|---|---|
| A live key, secret or publishable, with the client tokens made from it | 120 |
| A test key, secret or publishable, with the client tokens made from it | 30 |
| Client sessions opened with one publishable key | 30 sessions |
| A key with its own rate_limit_per_minute | Its own, from 1 to 100,000 |
Every response to a request with a valid credential carries the state of its window:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the window |
X-RateLimit-Remaining | Requests left in it |
X-RateLimit-Reset | Seconds until the window starts again |
Past the limit, the answer is 429 rate_limited with Retry-After in seconds. GET /v1/me gives a credential's limit as rate_limit_per_minute. A browser can read these headers too: the API exposes them to cross-origin pages.
Monthly quotas#
An organization can have a monthly number of documents, set by ReceViz, and a key can have its own monthly_quota, set in the console. Both count every extraction ReceViz accepted in the calendar month (UTC), including those that later failed; a replayed idempotent request is not counted again.
- Over the organization's quota:
429 quota_exceeded. - Over the key's:
429 key_quota_exceeded.
Either way, Retry-After counts down to the start of the next month. Watch usage in the console's Usage page, or with GET /v1/usage (usage.read): the calling application's requests, documents, pages, error rate, latency and a day-by-day series over the last days (1 to 90, default 30), and the organization's documents so far this month.
Documents#
| Limit | Value | Past it |
|---|---|---|
| File size | 20 MB, or less if set for the organization | 400 file_too_large |
| Image size | 14,000 px on a side and 60 megapixels | 400 image_too_large |
| Pages in a PDF or a multi-page TIFF | 30, or fewer if set for the organization | 400 too_many_pages |
| Read while you wait | Up to 10 MB and 3 PDF pages | Queued instead (202, warning processed_async) |
| Time to read while you wait | 90 seconds | 504 processing_timeout |
| Time to read a queued document | 10 minutes, up to 3 attempts | Fails with processing_timeout |
| metadata | 2048 bytes; only the first 50 keys are kept | 400 invalid_metadata |
| client_ocr | 2,500 lines a page, 30 pages | Lines and pages beyond are ignored |
| options.known_merchants | 250 names of 60 characters | Names beyond are ignored; longer ones are cut |
| Idempotency-Key | 128 characters, remembered for 24 hours | 400 invalid_idempotency_key |
Formats#
| Format | Notes |
|---|---|
| JPEG, PNG, WebP | Turned upright by their EXIF orientation and converted to RGB before reading. |
| TIFF | A multi-page TIFF is read page by page; each frame counts as a page. |
| HEIC, HEIF | Read like any other photo. A ReceViz deployment built without HEIC support answers 400 heic_unsupported instead; send JPEG or PNG there. |
| Rendered page by page, with form fields never drawn, or handed whole to a recogniser that reads PDFs itself. A password-protected PDF is refused (pdf_encrypted). |
A file's type is decided by its bytes, never by its name or its declared content type. When the declared type is wrong, the file is still read, and the result carries the warning declared_type_mismatch. AVIF and anything else is refused with 400 unsupported_media_type.
HEIC from iPhones
The iOS and Android SDKs upload JPEG. In Safari the Web SDK's normalizeImage converts a HEIC photo to JPEG; browsers that cannot decode HEIC pass the file through unchanged, for ReceViz to read.
Keys, applications and webhooks#
| Limit | Value |
|---|---|
| Applications per organization | 20, unless ReceViz set another limit |
| Active keys per application | 25 |
| Entries in each of a key's restriction lists | 50 |
| Key expiry, when set | 1 to 3650 days |
| Rotation grace period | 0 to 168 hours, 24 by default |
| Client token lifetime | 60 to 3600 seconds, 600 by default |
| Webhook endpoints per application | 5 |
| Document types per organization | 50 active, unless ReceViz set another limit |
| Proposals from a description, in the console | 30 an hour per organization |
Definitions#
| Limit | Value |
|---|---|
| Fields, counting nested ones | 120 |
| Nesting of objects and arrays | 3 levels |
| Items returned for an array | 1 to 500, 100 by default |
| Aliases per field | 25, each up to 60 characters |
| Values of an enum | 60 |
| Rules | 30 |
| A validation pattern | 200 characters, without nested quantifiers |
| A field's description | 500 characters |
See Document types for what each part of a definition does.
How long things are kept#
The request log (metadata only) is kept for 90 days and the audit log for 400. How long extraction results, webhook payloads and quality records are kept is set by your data policy; see Data and privacy.