Rate limiting

The Xem API limits how many requests each client can make, to keep the service responsive and to slow down password guessing. Limits are counted per client IP address and per endpoint.

Limits

Endpoint	Limit per IP address
`POST /api/v1/auth/login`	5 per minute
`POST /api/v1/auth/register`	3 per hour
`POST /api/v1/auth/password-reset`	3 per hour
`POST /api/v1/auth/password-reset/verify`	10 per hour
`POST /api/v1/auth/refresh`	10 per minute
`POST /api/v1/files/upload`	20 per minute
`POST /api/v1/emails`	100 per minute
`GET /api/v1/analytics/…` (all analytics together)	100 per minute
`GET /t/open` and `GET /t/click/…` (email tracking)	1,000 per minute each
Every other endpoint	100 per minute, per endpoint

Health checks at /health and /api/v1/health are not limited. The limit is stored in Redis, so it is shared by every API instance. If Redis is unavailable, each API instance falls back to a single in-memory limit of 20 requests per second per IP address, and the stricter limits above do not apply. Self-hosted installs should keep Redis running.

Response headers

Every limited response includes:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute for this endpoint
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	When the window resets, as a Unix timestamp

When you exceed the limit

The API returns 429 Too Many Requests with this body:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again later.",
  "retry_after": 60,
  "limit": 5,
  "window": 60
}

retry_after is the number of seconds to wait before trying again: the length of that endpoint’s window.

Retry with backoff

Wait for retry_after seconds, or back off exponentially if it is missing, and add a little random jitter so many clients do not retry at once:

async function withRetry<T>(call: () => Promise<Response>, attempts = 5): Promise<Response> {
  for (let i = 0; ; i++) {
    const res = await call();
    if (res.status !== 429 || i === attempts - 1) return res;
    const body = await res.clone().json().catch(() => ({}));
    const seconds = body.retry_after ?? 2 ** i;
    await new Promise((r) => setTimeout(r, seconds * 1000 + Math.random() * 250));
  }
}

When you send email through the API, include a requestId so a retried request cannot send the same message twice. See the quickstart.

Staying under the limit

Send campaigns to lists from the app, instead of one API call per recipient.
Cache data that rarely changes, such as templates and lists.
Spread scheduled jobs out instead of starting them all on the minute.
Watch X-RateLimit-Remaining and slow down before it reaches zero.

Self-hosted installs can change these limits in server/internal/api/middleware/ratelimit.go.

Introduction

Start here

Core Concepts

Authentication

Forms

Analytics

Email Tracking

Subscriptions