Rate limiting

Documentation Index

Fetch the complete documentation index at: https://docs.botdog.co/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

The API enforces rate limits to protect the service and ensure fair usage. Limits are applied per API key (the same key you send as x-api-key), not per IP address. Each quota uses a sliding window (e.g. “60 requests per 60 seconds”). Plan-specific quotas may still apply elsewhere; when in doubt, treat limits as documented in your contract or dashboard.

​

Limits by endpoint

All paths below are under the /v1 prefix (for example, GET /v1/campaigns). Default for API-key routes: Any authenticated route that uses the standard API key guards but does not declare its own limit falls back to 60 requests / 60 s per API key.

​

Response headers

When the rate limit check runs successfully, responses include:

• X-RateLimit-Limit — maximum requests allowed in the current window.
• X-RateLimit-Remaining — requests remaining in the current window.
• X-RateLimit-Reset — Unix timestamp in milliseconds when the limit window resets.

These headers are set on successful responses (HTTP 2xx) as well as on 429 responses, so clients can throttle before hitting the cap.

​

When you hit the limit

You will receive 429 Too Many Requests. The response includes:

• The same X-RateLimit-* headers as above.
• Retry-After — suggested wait time in seconds before retrying.

Stop hammering the API: honor Retry-After or wait until X-RateLimit-Reset, then retry with a small buffer.

​

Backoff strategy

1. Prefer Retry-After on 429 responses, or sleep until X-RateLimit-Reset (with a small buffer).
2. If those headers are missing, use exponential backoff (e.g. 1s, 2s, 4s, …) with jitter, and cap the maximum delay.

​

Operational note

If the rate-limit backend is temporarily unavailable, the API may allow the request without setting X-RateLimit-* headers. This is rare; normal operation always includes those headers when the check succeeds.