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

# Doohick API Rate Limits, Quotas, and Backoff Strategies

> Understand Doohick API rate limit tiers, read the response headers that track your quota, and handle 429 errors gracefully with backoff logic.

The Doohick API enforces rate limits to maintain reliability and fair usage across all customers. Limits apply per API key and are measured in two windows: requests per minute (to protect against bursts) and requests per day (to enforce plan-level quotas). When you exceed either limit, the API returns a `429 Too Many Requests` response.

## Rate limit tiers

Your rate limits depend on the Doohick plan associated with your account:

| Plan       | Requests per day | Requests per minute |
| ---------- | ---------------- | ------------------- |
| Starter    | 1,000            | 30                  |
| Pro        | 50,000           | 300                 |
| Enterprise | Unlimited        | Custom              |

Enterprise customers can negotiate custom per-minute limits to match their specific traffic patterns. Contact your account manager to adjust your configuration.

## Rate limit headers

Every API response — including successful ones — includes the following headers so you can track your consumption in real time:

| Header                  | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per day on your plan         |
| `X-RateLimit-Remaining` | Requests remaining in the current daily window        |
| `X-RateLimit-Reset`     | Unix timestamp (UTC) when the daily limit resets      |
| `Retry-After`           | Seconds to wait before retrying (only present on 429) |

Read these headers proactively in your integration code to slow down before you hit the ceiling, rather than reacting only after a `429` arrives.

## Handling 429 errors

When you exceed a rate limit, the API returns a `429` response with a structured error body:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your daily API request limit.",
    "retry_after": 3600
  }
}
```

`retry_after` is the number of seconds to wait before your next request is likely to succeed. Use this value — or the `Retry-After` response header — to drive your retry logic.

The following example implements exponential backoff with a cap on maximum attempts:

```javascript theme={null}
async function fetchWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const retryAfter = response.headers.get('Retry-After') || 2 ** attempt;
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error('Max retries exceeded');
}
```

On each `429`, the function reads the `Retry-After` header. If the header is absent — for example, on a burst-limit hit — it falls back to an exponentially growing delay (`1s`, `2s`, `4s`, `8s`, `16s`).

<Note>
  Exponential backoff prevents a thundering-herd problem where many clients retry simultaneously and immediately re-trigger the same rate limit.
</Note>

## Best practices

Follow these guidelines to stay within your limits and build a resilient integration:

* **Cache responses where possible.** Data that doesn't change frequently — such as account settings or static reference lists — should be cached locally rather than re-fetched on every operation.
* **Batch requests.** Where the API supports batch operations, prefer a single batched call over many individual requests.
* **Use webhooks instead of polling.** Subscribe to Doohick webhooks for event-driven updates rather than repeatedly querying endpoints to detect changes.
* **Monitor your `X-RateLimit-Remaining` header.** Build alerting into your integration so you are notified before the remaining quota drops to zero.
* **Upgrade your plan if needed.** If your workload consistently approaches daily or per-minute limits, upgrading to a higher tier is the most durable solution.

<Tip>
  Track your live API usage at any time from the **Settings → API Usage** page in your Doohick dashboard. The usage graph updates in near-real time and breaks down consumption by endpoint, making it easy to spot which calls consume the most of your quota.
</Tip>