Rate Limiting

Overview

To ensure equitable access and maintain performance for all users, the WatchEye API enforces rate limiting on all endpoints. This section provides details on how rate limiting works, its default configurations, and how to manage and respond to rate limit constraints.

Default Rate Limit Configuration

By default, the rate limit for the API is 600 requests per minute. The limit is enforced with a 60-second fixed window: each request consumes one slot from the current window, and the counter resets once the window expires. Pacing requests evenly over the minute is the safest way to stay below the limit.

Adjusting Your Rate Limit

If you need a higher request rate, adjustments can be made on a case-by-case basis. To initiate a review or request a change in your rate limit:

1. Contact Global Data support.
2. Provide a clear reason for the requested change, along with any data or justification that supports your use case.

Once your request is reviewed, the support team will contact you with a decision or request further information.

Exceeding Rate Limit & Response Handling

When the rate limit is exceeded, the API responds with a 429 Too Many Requests status. Applications should implement a back-off strategy and wait before retrying.

Every response (both successful responses and 429s) includes headers describing the current rate-limit state:

• X-RateLimit-Limit - the maximum number of requests allowed in the current 60-second window.
• X-RateLimit-Remaining - the number of requests still available before the limit is hit.

On a 429 response, two additional headers tell you exactly how long to wait:

• Retry-After - the number of seconds to wait before the next request will be accepted. This is the value to use to schedule your retry.
• X-RateLimit-Reset - the Unix timestamp (seconds since the epoch) at which the current window will reset.

For example, a successful response when the limit is 600 per minute and 1 call has been made:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599

A 429 response when the limit has just been hit and the window resets in 42 seconds:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 42
X-RateLimit-Reset: 1740000042

HTTP header names are case-insensitive; the headers above may appear in lowercase depending on your HTTP client.

Best Practices

• Honour Retry-After: On a 429 response, schedule your retry for Retry-After seconds in the future rather than using a fixed sleep. This keeps your back-off correctly sized for the actual reset window.

• Watch X-RateLimit-Remaining: Slow down pre-emptively when the remaining count drops near zero rather than waiting for a 429. Many integrations add a small dynamic pause once the remaining count falls below a threshold.

• Spread out batch work: If you need to process a large batch (for example, creating many entities in one go), distribute the requests evenly over time instead of bursting.

• Centralise rate-limit handling: Implement the 429 / Retry-After handling once in your HTTP client wrapper so every call site benefits, rather than spreading retry logic through individual endpoints.