Rate Limits

• No hard limit currently — fair-use applies.
• Batch cap — POST /api/v1/inventory accepts at most 500 records per request. Larger batches return 400 BATCH_TOO_LARGE.
• Max runtime — a single request may run up to 300 seconds (Vercel hard ceiling). Large batches are expected to fit well under that; split if you're brushing the limit.

Design for these numbers; we monitor and will flag outliers before blocking.

• 60 requests / minute per API key on PATCH /api/v1/inventory, GET /api/v1/inventory/{vin}, and /api/v1/dealers.
• 10 batches / minute per API key on POST /api/v1/inventory — each batch is up to 500 records, so this is 5,000 records/minute.
• Feed pulls (HTTPS pull or SFTP) — cadences faster than hourly require coordination.
• Widget endpoints (/api/v1/widget/*) — no per-key limit; IP-level bot protection applies.

When hard limits are enforced, a 429 response will include a Retry-After header with the seconds to wait. Implement exponential backoff with jitter today so the behavior is already correct when rollout happens:

• First retry: 1s + random jitter up to 500ms.
• Subsequent retries: double the delay, cap at 60s.
• Give up after 5 attempts and log.

• Batch aggressively — 500-record batches are cheaper than 500 single-record requests.
• Sync deltas, not snapshots, via the API — use feed pulls for full snapshots; use POST + PATCH for incremental updates and sold events.
• Coalesce PATCH calls — if a VIN flips sold-then-available-then-sold within seconds, send the final state only.
• Respect Retry-After when it appears.

Enterprise plans include negotiated headroom (10–100x the fair-use ceilings, depending on volume). Email sales@truckradar.ai if you're syncing more than 25,000 records/day or 100,000 records total.