Errors - Chatarmin CX Docs

Every Public API v1 error returns a consistent JSON envelope:

{
  "success": false,
  "code": "TICKET_NOT_FOUND",
  "message": "Ticket not found",
  "request_id": "req_abc123",
  "retry_after": 42
}

Field	Description
`success`	Always `false`
`code`	Machine-readable error code — match on this in integrations
`message`	Human-readable detail — log only; do not branch logic on wording
`request_id`	Correlation ID for support and log lookup
`details`	Optional structured context (validation issues)
`retry_after`	Present on rate limit errors — seconds to wait

Error codes

Code	HTTP	When
`API_KEY_REQUIRED`	401	Missing `cx-api-key` header
`INVALID_API_KEY`	401	Key not found or revoked
`API_KEY_ORG_MISSING`	401	Key has no organization binding
`FORBIDDEN_SCOPE`	403	Key lacks required scope for the route
`VIEW_NOT_FOUND`	404	Unknown `view_id`, cross-org view, or view not visible to linked agent
`TICKET_NOT_FOUND`	404	Ticket number does not exist in the organization
`ATTACHMENT_NOT_FOUND`	404	Unknown attachment ID, or it belongs to another organization
`INVALID_FILTER`	400	Invalid filter or view configuration
`VALIDATION_ERROR`	400	Malformed query params or unknown fields
`IDEMPOTENCY_KEY_CONFLICT`	400	Same `Idempotency-Key` reused with a different request body
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	The first request for this `Idempotency-Key` is still processing — retry shortly
`RATE_LIMIT_EXCEEDED`	429	Per-route rate limit hit
(none)	500	Unexpected server error — retry with backoff

Validation errors

VALIDATION_ERROR responses may include a details object with field-level issues from Zod validation (for example invalid UUID format on view_id).

Support and debugging

When contacting support, include:

request_id from the error response
HTTP method and path
Timestamp (UTC)
API key name (never the secret value)

Rate limits — RATE_LIMIT_EXCEEDED and Retry-After
Authentication — scope and key errors
OpenAPI reference — per-endpoint error response schemas