> ## Documentation Index
> Fetch the complete documentation index at: https://developer.klikit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Stable machine-readable error codes returned by the Partner API.

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

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.