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

# Knouds API rate limits and back-off strategies

> Per-tier request limits, the response headers that track your quota in real time, and how to handle 429 responses and back off gracefully.

The Knouds API enforces rate limits per user, per route, per 60-second window. Limits are tied to your **tier**, independent of which capabilities your key carries. When you exceed the limit, requests return `429` until the current window resets.

## Per-tier limits

| Tier       | Limit                                      |
| ---------- | ------------------------------------------ |
| Enterprise | unlimited                                  |
| Business   | 1,000 req/min                              |
| Pro        | 100 req/min                                |
| Free       | (no external API access by product design) |

Free tier has no API key access — the table is shown for completeness only. Pro+ unlocks key creation.

<Note>
  Rate limits are tracked independently per route. Calls to `POST /api/workflows/:slug/run` and `POST /api/models/:internalName/run` each maintain their own bucket — calls to one do not consume quota on the other.
</Note>

## Rate limit headers

Every successful response from a rate-limited endpoint includes three headers that reflect the state of your current bucket:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714512000
```

| Header                  | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The maximum number of requests allowed per window for your tier             |
| `X-RateLimit-Remaining` | Requests remaining in the current 60-second window                          |
| `X-RateLimit-Reset`     | Unix epoch second at which the current window resets and your quota refills |

You can inspect these headers with `curl -i`:

```bash theme={null}
curl -i https://knouds.ai/api/workflows/my-pipeline/run \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{}}' | grep -i 'ratelimit\|retry-after'
```

## 429 responses

When you exceed the limit, the API returns HTTP `429` with the `RATE_LIMIT_EXCEEDED` code:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "tier": "pro",
  "limit": 100,
  "retryAfter": 12
}
```

The response also includes the standard rate limit headers plus a `Retry-After` header (in seconds) indicating exactly how long to wait before retrying:

```
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714512012
```

## Recommended back-off pattern

Check `X-RateLimit-Remaining` before dispatching batch calls. If the value falls below `5`, pause and wait until `X-RateLimit-Reset` before sending more requests. When you receive a `429`, read the `Retry-After` value and sleep for that many seconds before retrying.

```javascript theme={null}
async function runWithBackoff(slug, inputs) {
  const response = await fetch(
    `https://knouds.ai/api/workflows/${slug}/run`,
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.KNOUDS_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ inputs }),
    }
  );

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '10', 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return runWithBackoff(slug, inputs);
  }

  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '999', 10);
  if (remaining < 5) {
    const reset = parseInt(response.headers.get('X-RateLimit-Reset') || '0', 10);
    const waitMs = Math.max(0, reset * 1000 - Date.now());
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }

  return response.json();
}
```

If your workload consistently hits rate limit walls, upgrading your tier raises your quota — from 100 req/min on Pro to 1,000 req/min on Business, or unlimited on Enterprise.