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`, `GET /agents`, `GET /reports/metrics`	60 requests / minute
Detail	`GET /tickets/:ticketNumber`, `GET /tickets/:ticketNumber/messages`	120 requests / minute
Write	`POST /tickets`	30 requests / minute
Analytics	`POST /reports/query`	10 requests / minute

GET /health uses the detail tier. List, detail, write, and analytics limits are independent. The metric catalog uses the list tier, not the analytics query tier.

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.