Rate limits and versioning

Rate limits

The following table lists the limits:

Limit	Applies to
3,000 requests a minute	Each API key, across all endpoints except image addresses
600 requests a minute	Image addresses, for each client IP address. For more information, see Images.
100 items	Each page of a list (limit)

If you exceed a limit, the API returns 429 rate_limited with a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/problem+json

{"type": "https://docs.luxorr.io/errors#rate_limited", "title": "Rate limited", "status": 429, "code": "rate_limited", "detail": "…"}

Wait, and then retry the same request with the same Idempotency-Key. Limits apply to each key separately.

To stay under the limits, do the following:

• Read the event feed with limit=100 instead of polling each link.
• Spread a large send, such as the birthday links for a whole segment, over a few minutes.
• Use one key for each system.

Versioning

The major version is in the path: /v1.

Within v1, changes only add to the API:

• New endpoints, optional request fields, and query parameters.
• New response fields and event types.
• New error codes and enum values.

Your client must ignore unknown fields, skip unknown event types, and use the HTTP status when it gets an unknown error code.

Breaking changes get a new major version, such as /v2. Luxorr announces a new major version in advance, and it runs alongside v1 while you migrate.