# Limitations and Requirements

To ensure the continued stability of our platform and combat abuse, we enforce a handful of restrictions on incoming request rate on an IP-by-IP basis. Hence, if you're on a VPN, proxy or a shared network in general, the requests of other users on this network might affect your allowance.

# General requirements for connection

easyroam supports HTTP/1.1 and HTTP/2, and requires TLS/SSL to be used for both on all endpoints.
The API is available at https://api.easyroam.de and the authentication server at https://auth.easyroam.de.

Note

Insecure request will automatically receive a 30x redirect to a secure equivalent of the URL.

The following requirements are placed additionally on incoming HTTP requests:

You MUST include a User-Agent header in your request
You MUST NOT include a Via header in you request

Note

Noncompliance with these requirements might result in your request being denied or the API responding in unexpected ways.

# General rate limits

We have a global rate limit of ~6 requests per second per IP in place for api.easyroam.de and auth.easyroam.de.

Should you exceed the rate limit you will receive a 429 response from our servers. The client will receive a response like this:

Status Code: 429
Retry-After: 58
Content: API calls quota exceeded! maximum admitted 5 per 1s.

The Retry-After header is expressed in seconds.

If your request doesn't get rate limited, you can use the following headers to know how many request you have left in the give time period

Header	Description
`X-Rate-Limit-Limit`	Maximal number of requests the endpoint allows per its time period (e.g. 5m, 1s)
`X-Rate-Limit-Remaining`	Remaining number of requests within your quota for the current time period
`X-Rate-Limit-Retry-After`	Timestamp of the end of the current time period, as UNIX timestamp (ISO 8601)

# Endpoint specific rate limits

We reserve the right to implement endpoint specific rate limits at any point in time and without prior notice. At this time however, there are no endpoint specific rate limits in place.

# Limitation of result sizes

Some endpoints return a collection of results. Some clients might not be able to handle these large result sets, which is why endooints that are expected to return a collection typically take an offset and limit query parameter.