# Rate Limiting

To ensure stability and fair usage across all consumers, rate-limiting policies apply to all Journey Planner API requests. Users without an agreement with Entur are subject to the default policy, while Entur partners receive a custom policy.

## Policies

There are two separate policies:

-   **Trip-request** — One policy only applies for trip-requests as these are the most resource consuming.
-   **Other-request** — One policy applies for all other requests available in the GraphQL API.

Each policy is split into two elements:

-   **Quota** — The number of requests per minute, calculated using a counter within a time window of one minute that starts at the first request and is reset every minute. E.g. given a quota policy of 10 requests per minute, a violation will occur if a request is sent after the counter has reached its limit of 10 requests within the current time window.
-   **Spike Arrest** — The number of requests per second, calculated by keeping track of time elapsed since last request. E.g. a spike arrest policy of two requests per second means a violation will occur if a request is sent within half a second after the previous request.

## Policy levels

| Level | Trip-request Quota | Trip-request Spike Arrest | Other-request Quota | Other-request Spike Arrest |
|---|:---:|:---:|:---:|:---:|
| Non-identified consumers | 30 | 2 | 60 | 20 |
| Consumers identified with `ET-Client-Name` | 500 | 150 | 1000 | 200 |
| Entur Partners | custom | custom | custom | custom |

All requests **must** include the `ET-Client-Name` header. Use a value that uniquely identifies your company and application, in the form `<company>-<application>` (lowercase, no spaces). For details, see [Authentication](/docs/authentication#open-services).

## Monitoring policy status

It is expected that consumers have control over their policy status with respect to traffic patterns. All responses from the service contain headers with details about current usage and remaining quota. When spike arrest occurs, headers are supplied containing the spike arrest policy itself. If your request violates one of the policies you will get a response with status code `429` ([Too Many Requests](https://datatracker.ietf.org/doc/html/rfc6585#section-4)).

### Quota headers

All responses include quota headers (except when there is a spike arrest violation):

```
Rate-Limit-Allowed: 30
Rate-Limit-Available: 29
Rate-Limit-Expiry-Time: Mon Jan 16 2023 12:17:34 GMT-0000 (UTC)
Rate-Limit-Range: "per-minute"
Rate-Limit-Used: 1
```

### Spike arrest headers

Only returned upon a spike arrest violation:

```
Spike-Allowed: 2
Spike-Range: per-second
```

## Retry policy

It makes sense for clients to implement a conservative retry policy on **spike arrest violations** as spikes in traffic loads may occur.

Clients should **NOT** implement a retry policy for **quota violations**. Upon quota violation, clients should wait at least until the time indicated by `Rate-Limit-Expiry-Time` before trying again.