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

# Rate Limits

> How the Sevalla API enforces rate limits, including per-tier limits, response headers, and how to handle 429 errors.

To keep the platform stable for everyone, the Sevalla API enforces rate limits on all requests. When you exceed a limit, the API returns a `429 Too Many Requests` response.

## Rate limit tiers

Limits are scoped per company or per service depending on the operation type.

| Tier             | Limit   | Scope                 |
| ---------------- | ------- | --------------------- |
| Service creation | 20/hour | Per company           |
| Service mutation | 10/min  | Per service + company |
| Deployment       | 10/min  | Per service + company |
| General write    | 30/min  | Per company           |
| Logs             | 30/min  | Per company           |
| Read             | 400/min | Per company           |

**Service creation** covers `POST` requests that create new applications, databases, static sites, or other resources. **Service mutation** covers `PUT`, `PATCH`, and `DELETE` requests that modify an existing service. **General write** covers all other write operations that don't fall into a more specific tier.

## Response headers

Every response includes rate limit headers so you can track your usage without guessing.

| Header                  | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `x-ratelimit-limit`     | Maximum number of requests allowed in the current window.                |
| `x-ratelimit-remaining` | Number of requests remaining in the current window.                      |
| `x-ratelimit-reset`     | Seconds remaining until the current rate limit window resets.            |
| `x-request-id`          | Unique identifier for the request. Include this when contacting support. |

Example response headers:

```
x-ratelimit-limit: 400
x-ratelimit-remaining: 398
x-ratelimit-reset: 5
x-request-id: req-a1b2c3d4e5
```

## Handling 429 responses

When you hit a rate limit, the API returns a `429` status code. The `x-ratelimit-reset` header tells you how many seconds to wait before retrying.

```typescript theme={null}
async function makeRequest(url: string, headers: Record<string, string>): Promise<Response> {
  const resp = await fetch(url, { headers });

  if (resp.status === 429) {
    const wait = Number(resp.headers.get("x-ratelimit-reset"));
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    return makeRequest(url, headers);
  }

  return resp;
}
```

<Tip>Check `x-ratelimit-remaining` before making requests. If you're running low, slow down proactively instead of waiting to get throttled.</Tip>

<Warning>Always use exponential backoff with jitter when retrying. Retrying in a tight loop will keep you rate limited longer.</Warning>