# Rate Limits & Headers

> Rate limiting, quotas, and response headers for the Fleetwork API.

Source: https://docs.fleetwork.vn/en/introduction/rate-limits

## Limits by Plan

| Limit | Free | Premium | Internal |
|---|---|---|---|
| Requests/second | 2 | 10 | 100 |
| Requests/minute | 60 | 500 | 5,000 |
| Requests/hour | 1,000 | 20,000 | Unlimited |
| Requests/day | 10,000 | 200,000 | Unlimited |
| Requests/month | 100,000 | 5,000,000 | Unlimited |
| Monthly quota | 100,000 | 5,000,000 | Unlimited |
| Max API keys | 1 | 5 | 20 |
| Burst allowance | 5 | 50 | 200 |

## Rate Limit Headers

Every response from API-Key-authenticated requests includes:

| Header | Description |
|---|---|
| `X-RateLimit-Limit` | Max requests/minute for the key (`0` = unlimited) |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | ISO 8601 timestamp when the window resets |
| `Retry-After` | _(HTTP 429 only)_ Seconds to wait before retrying |

## Quota Headers

| Header | Description |
|---|---|
| `X-Quota-Limit` | Monthly quota limit |
| `X-Quota-Remaining` | Remaining quota this month |
| `X-Quota-Used` | Quota consumed this month |

## Informational Headers

| Header | Description |
|---|---|
| `X-API-Key-Id` | UUID of the authenticated API key |
| `X-Module-Id` | UUID of the accessed module |
| `X-Module-Name` | Name of the accessed module |

## Example Responses

### Normal response

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 497
X-Quota-Limit: 5000000
X-Quota-Remaining: 4999823
X-Quota-Used: 177
X-API-Key-Id: 3513c8c9-6ea7-47c3-ba37-188b842fa590
X-Module-Name: Job Management
Content-Type: application/json
```

### Throttled response

```http
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
Retry-After: 45
Content-Type: application/json
```

## Handling Rate Limits

```javascript
async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}
```