fileAI limits how many API requests a project can make in each time window. Every response tells you how much of the allowance is left, and a request over the limit gets 429 Too Many Requests with the number of seconds to wait. Pace your client with the headers and you rarely see a 429 at all.

How it works

Two limits apply, each with its own quota and window:
  • An upload request counts against both: file-upload is checked first, then default. An upload rejected by file-upload never reaches default.
  • Each request costs one, whatever it contains. A batch upload registering 100 files costs the same as a single upload, so batching is the cheapest way to send many files.
  • Requests are counted per project. Every API key on the same project draws on the same allowance.
  • The window is fixed: it starts with the first request, and the full allowance returns when it ends. It does not refill gradually.

Headers

Every authenticated response carries these headers, success or error: Read your actual quota and window from RateLimit-Policy; they can differ between projects.

The 429 response

A request over a limit is rejected before it runs, so nothing is created or changed. The body is a problem document with code RATE_LIMITED and a retryAfter member that matches the Retry-After header:
429 Too Many Requests
detail is File upload rate limit exceeded when the file-upload limit was hit. Branch on code, not detail. The RateLimit header on a 429 describes the limit that was breached.

Back off

1

Watch the headers

Parse RateLimit on every response. When r gets low, spread the remaining requests over the t seconds left instead of sending them at once.
2

On a 429, wait Retry-After

Sleep for Retry-After seconds (or retryAfter from the body), then retry the same request. Waiting longer is fine; retrying sooner just earns another 429.
3

Make retries safe

Send an Idempotency-Key on writes. A 429 is never stored against the key, so the retry runs normally.
Several workers on one project share one allowance. Coordinate them, for example with a shared queue, rather than letting each back off on its own.

Errors

Problem documents, codes and when to retry.

Idempotent requests

Retry writes without applying them twice.

Uploads

Batch uploads cost one request for up to 100 files.

Troubleshooting

Common failures and how to fix them.