> ## Documentation Index
> Fetch the complete documentation index at: https://traddal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Per-organization request limits, the 429 response, and how to handle it.

Every authenticated API surface is rate limited **per organization** — the
limit is shared across all of your API keys and users, so rotating keys does
not raise it. The limits below are the defaults and may vary by plan.

| Scope                                                                                                                                         | Limit                         | Sustained   |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----------- |
| All API endpoints                                                                                                                             | 2,000 requests per 10 seconds | \~200 req/s |
| `POST /v1/consignments` (create)                                                                                                              | 300 requests per 10 seconds   | \~30 req/s  |
| AI assistant chat (per user)                                                                                                                  | 20 messages per 60 seconds    | \~1 msg/3s  |
| `/v1/classify` with `image_url`, `product_url`, or an agentic/web-grounded mode                                                               | 120 items per 60 seconds      | \~2 items/s |
| Heavy work: PDF rendering (invoices, statements, identity packs), export downloads, label generation, manifest invoice bundles, global search | 60 requests per 60 seconds    | \~1 req/s   |

Unauthenticated surfaces (public tracking, the duty portal, sign-in, OAuth
callbacks, webhook URLs with an unknown token) are limited **per visitor IP**
instead — 120 requests per 60 seconds for public lookups, 10 per 60 seconds
for the tracking gate, portal unlock (also per link) and sign-in attempts.

Customer-scoped API keys and customer portal logins get their own bucket
under your organization, so a single customer cannot exhaust your limit.

Limits use a sliding window, so short bursts above the sustained rate are
fine as long as the 10-second total stays under the ceiling.

## The 429 response

When a limit is exceeded the API answers `429 Too Many Requests` with a
`Retry-After` header (seconds):

```json 429 theme={null}
{
  "error": "rate_limited",
  "message": "Too many requests — this endpoint is limited per organization. Retry after the indicated delay, or use the shipment-import API for large batches."
}
```

Nothing was processed — the request never reached the database, so retrying
after the delay is always safe.

## Handling limits well

* **Respect `Retry-After`.** Sleep for the indicated seconds, then retry.
  Add jitter if you run parallel workers.
* **Use exponential backoff** for repeated 429s rather than tight retry loops.
* **Batch instead of flooding.** If you need to create thousands of
  shipments at once, use the shipment-import flow in the
  dashboard (Shipments → Import) — it accepts a whole file at once and
  processes it in the background at our pace.
* **Spread scheduled jobs.** Nightly syncs that fire everything at 00:00
  sharp compete with themselves; stagger or stream the work.

If your integration legitimately needs more sustained throughput, contact
support — limits can be raised per organization.