Skip to main content

Overview

Unsiloed rejects requests for two different reasons, and the status code tells you which one applies:
  • 429 Too Many Requests comes from your organization’s policy. You sent requests faster than your plan’s per-second limit. See Rate Limits.
  • 503 Service Unavailable comes from platform capacity. The platform is busy right now, whatever your own request rate. It is not caused by your organization’s usage.
Both responses include a 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 a 503 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 a 503 with Retry-After: 5.

Responding to a 503

  1. Wait at least the number of seconds in Retry-After.
  2. Resubmit the same request. No job was created, so this does not cause duplicates.
  3. If you get another 503, keep waiting for Retry-After and add backoff with jitter so many clients do not retry at the same moment.
  4. Cap the number of retries and surface an error if the platform stays busy.
The retry helper in the API FAQ handles both 429 and 503 this way.
Do not retry a 503 immediately or in a tight loop. It delays recovery for everyone, including your own jobs that are already running.

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 400 and the message At 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/extract calls.
If a batch needs more requests than your remaining Extraction allowance, the whole batch is rejected with a 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 a job_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 returns 429 or 503, wait for Retry-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.

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