Error codes

Every non-2xx response includes error.code — a stable identifier you can branch on. The error.message field is informational and may be reworded over time, so don’t pattern-match against it.

Common codes

`error.code`	HTTP	When you see it	What to do
`REQUEST_INVALID`	400	Body / query / headers didn’t validate	Fix your request shape
`MISSING_AUTH`	401	No `Authorization` header on a protected endpoint	Set HTTP Basic with key+secret
`INVALID_CREDENTIALS`	401	Key/secret pair is wrong or revoked	Reissue or rotate via operator
`FORBIDDEN_SCOPE`	403	Credential is missing the required scope	Ask operator to widen scope
`RESOURCE_NOT_FOUND`	404	Resource doesn’t exist, or isn’t visible to your business	Check ids; do not retry
`IDEMPOTENCY_KEY_CONFLICT`	409	Same key reused with a different body	Investigate before retrying
`INVALID_TRANSITION`	422	The requested state change isn’t allowed (e.g. wrong order status)	Read the current state, branch on it
`RATE_LIMITED`	429	Too many requests	Back off and retry; see `Retry-After` header
`DOWNSTREAM_UNAVAILABLE`	502	A klikit-side dependency was unavailable	Retry with backoff
`INTERNAL`	500	Unexpected klikit-side failure	Retry with backoff; raise a ticket if persistent

How to handle errors

Always capture the top-level request_id alongside the error. We need it to find your request in our logs.
Retry only the codes documented as retryable — RATE_LIMITED, DOWNSTREAM_UNAVAILABLE, INTERNAL, and network timeouts. Retrying REQUEST_INVALID will never succeed.
Use exponential backoff with jitter for retries — start at 500ms, cap at 30s, give up after 5 attempts.
On IDEMPOTENCY_KEY_CONFLICT, stop and investigate. It means two code paths in your system both think they own the same key. Retrying without a fix is dangerous.

Get started

Core concepts

Webhooks

Reference receivers

API reference

Common codes

How to handle errors

​Common codes

​How to handle errors

Common codes

How to handle errors