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

# Responses & Errors

> The response envelope, list responses, and how failures are reported

Every response uses the same envelope, whether it succeeded or not.

| Field     | Type                    | Description                                        |
| --------- | ----------------------- | -------------------------------------------------- |
| `success` | boolean                 | Whether the request did what you asked             |
| `message` | string \| null          | Human-readable detail, usually `null` on success   |
| `code`    | string \| null          | Error code when something failed, otherwise `null` |
| `data`    | object \| array \| null | The payload                                        |

```json theme={null}
{
  "success": true,
  "message": null,
  "code": null,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Store"
  }
}
```

<Tip>
  Branch on `success`, not on the status code alone, and read `code` rather than
  `message` when handling failures. Messages are written for humans and can be
  reworded; codes are stable.
</Tip>

## List responses

Endpoints returning a list add `pages`: how many pages exist at the current page size. There's no total item count, so page until you reach it.

```json theme={null}
{
  "success": true,
  "pages": 5,
  "data": [
    // items
  ]
}
```

See [Filtering & Sorting](/api-reference/filtering) for narrowing, ordering and paging those results.

## Errors

```json theme={null}
{
  "success": false,
  "message": "Access denied.",
  "code": "AccessDenied",
  "data": null
}
```

`code` is a stable PascalCase identifier: `AccessDenied`, `NotFound`, `ObjectConflict`, `ValidationError`, `UpgradeRequired` and so on.

### Validation errors

Validation failures add `invalidFields`, one entry per problem, each formatted `Field: what's wrong`:

```json theme={null}
{
  "success": false,
  "message": "Validation failed",
  "code": "ValidationError",
  "data": null,
  "invalidFields": ["Name: Must be between 3 and 64 characters"]
}
```

Surface these to whoever submitted the data - they name the field and the rule it broke.

### HTTP status codes

| Status | Usually means                                         |
| ------ | ----------------------------------------------------- |
| `400`  | Malformed request, or validation failed               |
| `401`  | Missing, malformed or revoked API key                 |
| `403`  | Valid key, but it lacks the scope for this endpoint   |
| `404`  | Wrong ID, or a resource on an account you can't reach |
| `409`  | Conflicts with something that already exists          |
| `429`  | Too many requests                                     |
| `5xx`  | Our side                                              |

## Retrying

Retry `429` and `5xx` with increasing delays rather than immediately. Don't retry `4xx` responses other than `429` - the request will fail the same way until you change it.

If a `5xx` persists, check [status.komerza.com](https://status.komerza.com) before digging into your own code.

<Card title="Every error code" icon={<span className="kicon kicon-list" />} href="/api-reference/error-codes">
  The full list of `code` values, what triggers each and how to recover.
</Card>