Rate limits and versioning

Rate limits

Limit	Applies to
300 requests a minute	each API key, across all endpoints
600 requests a minute	each client IP, for key-less image URLs
1,000 recipients	each personal-link batch
100 items	each page of a list (limit)

Above a limit, the response is 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, then retry the same request with the same Idempotency-Key. Limits are per key.

To stay under the limits:

• Sync a local catalog copy instead of reading the catalog per page view.
• Read the event feed with limit=100 instead of polling each order.
• Use one key per system.

Versioning

The major version is in the path: /api/public/v1.

Within v1, changes are additive only. Each is listed in the changelog:

• new endpoints, optional request fields and query parameters;
• new response fields and event types;
• new error codes and enum values, such as a new source.

Clients must ignore unknown fields, skip unknown event types, and fall back to the HTTP status for an unknown error code.

Breaking changes get a new major version, such as /api/public/v2. It is announced in the changelog and runs alongside v1 during migration.

Forward-compatible shapes

These shapes allow future additions without breaking changes:

• items on an order is an array. It holds one item.
• shipments is an array. It holds at most one shipment.
• Money is always {amount, currency}, never a bare number.