Skip to main content
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.codeHTTPWhen you see itWhat to do
REQUEST_INVALID400Body / query / headers didn’t validateFix your request shape
MISSING_AUTH401No Authorization header on a protected endpointSet HTTP Basic with key+secret
INVALID_CREDENTIALS401Key/secret pair is wrong or revokedReissue or rotate via operator
FORBIDDEN_SCOPE403Credential is missing the required scopeAsk operator to widen scope
RESOURCE_NOT_FOUND404Resource doesn’t exist, or isn’t visible to your businessCheck ids; do not retry
IDEMPOTENCY_KEY_CONFLICT409Same key reused with a different bodyInvestigate before retrying
INVALID_TRANSITION422The requested state change isn’t allowed (e.g. wrong order status)Read the current state, branch on it
RATE_LIMITED429Too many requestsBack off and retry; see Retry-After header
DOWNSTREAM_UNAVAILABLE502A klikit-side dependency was unavailableRetry with backoff
INTERNAL500Unexpected klikit-side failureRetry with backoff; raise a ticket if persistent

​
How to handle errors

  1. Always capture the top-level request_id alongside the error. We need it to find your request in our logs.
  2. Retry only the codes documented as retryable — RATE_LIMITED, DOWNSTREAM_UNAVAILABLE, INTERNAL, and network timeouts. Retrying REQUEST_INVALID will never succeed.
  3. Use exponential backoff with jitter for retries — start at 500ms, cap at 30s, give up after 5 attempts.
  4. 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.