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 /classify, 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 at a steady interval. Every 5 seconds is a good default; jobs usually take seconds to minutes, so polling faster does not get you results sooner.
  • 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 have no per-organization rate limit, but they are covered by the platform-wide capacity limit. If a status request returns 503, wait for Retry-After before polling again instead of counting it as a failed job.
  • 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