> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.incarts.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Handle API validation, authorization, and retry responses

Incarts returns structured JSON errors and echoes `X-Correlation-ID` when available.

## Common status codes

| Status | Meaning                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- |
| `400`  | The request body, path, or header is malformed.                                          |
| `401`  | The API key is missing or invalid.                                                       |
| `403`  | The API key is valid but cannot access the requested project or scope.                   |
| `404`  | The resource does not exist or is not visible to the caller.                             |
| `409`  | There is an idempotency conflict, duplicate identifier, or conflicting resource state.   |
| `422`  | The request is syntactically valid but violates business rules or retailer capabilities. |
| `429`  | The caller is rate limited. Retry after the window resets.                               |
| `500`  | The API hit an internal error.                                                           |

## Retry guidance

Use idempotency keys for write requests and retry only when the operation can be safely repeated.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    See the headers expected by protected endpoints.
  </Card>

  <Card title="Create links" icon="link" href="/guides/create-links">
    Review business rules before retrying validation failures.
  </Card>
</CardGroup>