Overview
Unsiloed rejects requests for two different reasons, and the status code tells you which one applies:429 Too Many Requestscomes from your organization’s policy. You sent requests faster than your plan’s per-second limit. See Rate Limits.503 Service Unavailablecomes from platform capacity. The platform is busy right now, whatever your own request rate. It is not caused by your organization’s usage.
Retry-After header. In both cases the request was rejected before a job was created, so you can safely resubmit it once the wait is over.
Unsiloed does not queue excess requests on your behalf. A request is either accepted and processed, or it is rejected with a
429 or 503 that tells you when to try again. Accepted jobs run to completion.Platform busy
Before a new job is accepted, the API checks how many jobs are in progress across the platform. If that number is at its limit, the submission is rejected with a503 and a Retry-After between 5 and 60 seconds. The busier the platform, the longer the suggested wait.
This check applies to job submissions: POST /v2/extract, POST /splitter, and batch extraction. Jobs that were already accepted keep running and are not affected.
error.details.reason is queue_full and error.details.retry_after matches the Retry-After header.
Platform-wide capacity limit
The API also has a platform-wide capacity limit on total request volume across all customers. It protects the service during unusual traffic spikes, and you are unlikely to see it in normal use. When it is reached, any request to the processing and job status endpoints returns a503 with Retry-After: 5.
Responding to a 503
- Wait at least the number of seconds in
Retry-After. - Resubmit the same request. No job was created, so this does not cause duplicates.
- If you get another
503, keep waiting forRetry-Afterand add backoff with jitter so many clients do not retry at the same moment. - Cap the number of retries and surface an error if the platform stays busy.
429 and 503 this way.
Batch extraction
POST /batch/extract submits several files in one request. Two rules apply:
- At most 20 files per batch. A larger batch is rejected with
400and the messageAt most 20 files per batch. - Each file counts as one extraction request against your organization’s Extraction limit. A batch of 10 files uses the same allowance as 10 separate
POST /v2/extractcalls.
429 and no jobs are created. The files counted before the limit was reached still use up allowance, so wait for Retry-After before resubmitting.
If a batch is larger than your plan’s Extraction allowance, keep batches at or below that allowance, or submit files individually and pace them.
If the platform is busy, a batch is rejected with the same 503 described in Platform busy before any of its files are counted against your limit.
Polling job status
Extraction, classification, and splitting run asynchronously: you submit a job, receive ajob_id, and poll for the result.
- Poll every 3 to 5 seconds, with jitter. Jobs usually take seconds to minutes, so polling faster does not get you results sooner. Add a random offset to each wait so many jobs are not polled at the same instant.
- Set a time limit. Stop polling after a maximum number of attempts and treat the job as timed out on your side.
- Honor
Retry-After. Status endpoints are rate limited: each job can be polled up to 4 times per second, and your organization has a combined read limit (see Rate Limits). If a status request returns429or503, wait forRetry-After, then keep polling. A throttled poll says nothing about the job: do not count it as a failed job and do not resubmit. - Prefer webhooks. Webhooks notify you when a job finishes, so you do not need to poll at all.
- Spread out many jobs. When tracking a large number of jobs, stagger the polls instead of checking every job at the same instant.
Related
Rate Limits
Per-plan limits, rate limit headers, and the 429 response
Checking API Health
Confirm the API is up and your key works
Batch Extraction Cookbook
Process many documents concurrently with a worker pool
Support
Contact the team if 503s persist

