Rate limits

Rate limits keep one runaway integration from starving everyone else. The default is generous enough that well-behaved clients never hit it. Bursty clients should pace themselves using the headers we send on every response.

Defaults

600 requests / minute per integration, rolling window.
Each request costs 1 token by default. Some heavy endpoints (bulk customer upserts, cancel) cost 2.
The window is per-integration, not per-IP. Running clients from many regions doesn't bypass the cap.

Headers

Every authenticated response (200 or otherwise) carries:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1778230107

Limit: your current cap (the override if any, else 600).
Remaining: tokens left in the rolling window.
Reset: Unix timestamp when the window fully resets.

A well-behaved client checks Remaining before firing the next burst. If it's low, sleep until Reset minus a small safety buffer.

When you hit the cap

The 601^st request in the same window returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1778230107
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_requests",
    "message": "You have exceeded the rate limit for this integration.",
    "doc_url": "https://watchtraderhub.com/docs/api/errors#too_many_requests",
    "request_id": "req_…"
  }
}

Retry-After is the number of seconds until the next slot frees up. Honour it. Back off longer than that on repeated 429s. A client looping at exactly the cap is usually a queueing bug upstream rather than a real workload spike.

Recommended backoff

On 429, sleep Retry-After seconds (or up to min(60, Retry-After × 2^attempts) if you want jittered exponential backoff for repeated failures). Don't retry the same idempotent burst more than five times. Past that, the cap is genuinely too low for your workload.

Cost tokens

Most endpoints cost 1 token. A few cost 2 because they touch multiple rows or fan out to background work:

Endpoint	Cost
`POST /v1/customers`	2
`POST /v1/customers/bulk`	10
`POST /v1/orders`	2
`POST /v1/orders/:id/cancel`	2
everything else	1

X-RateLimit-Remaining after a 2-cost call decrements by 2, not 1. Plan accordingly.

Raise the cap

Per-integration overrides exist. If 600/min isn't enough for a legitimate workload (large catalog backfills, high-volume order ingestion), email support@watchtraderhub.com with your user_id (visible at GET /v1/me) and a quick note on the workload. Overrides take effect on the next request.

What counts against the limit

Every authenticated request, including ones that 4xx (validation, idempotency-conflict, 404).
Idempotent replays, they still hit the rate limiter.
Not: 401s before auth resolves (key isn't known yet, so there's nothing to count against).