Rate limits - Chatarmin CX Docs

Public API v1 enforces per-route rate limits keyed by API key (falling back to client IP when no key is present).

Limits by endpoint class

Endpoint class	Routes	Limit
List	`GET /tickets`, `GET /views`	60 requests / minute
Detail	`GET /tickets/:ticketNumber`, `GET /tickets/:ticketNumber/messages`	120 requests / minute

GET /health uses the detail tier. List and detail limits are independent — exhausting the list budget does not block detail requests.

Response headers

Every response includes rate limit headers:

Header	Meaning
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you exceed the limit, the API returns 429 with code RATE_LIMIT_EXCEEDED and a Retry-After header (seconds to wait). The error envelope may also include retry_after.

{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded.",
  "request_id": "req_...",
  "retry_after": 42
}

Best practices

Backoff on 429 — sleep for Retry-After seconds (or exponential backoff with jitter) before retrying.
Avoid tight polling loops — use reasonable intervals for agent tools; combine cursor pagination with backoff instead of hammering list endpoints.
Cache view metadata — GET /views changes infrequently; cache view id → name/filter mapping in your integration.
Batch sensibly — fetch message threads only for tickets you need, not every row in a list response.

Legacy `/public/*` limits

Deprecated legacy endpoints use different limits (30–300 requests / minute depending on endpoint). See the legacy OpenAPI reference if you still call /public/* during migration.