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

# Errors

> Error format and HTTP status codes returned by the Holos API.

The Holos API returns standard HTTP status codes and a consistent JSON error body.

## Error format

```json theme={null}
{
  "error": "Not found",
  "message": "Skill not found",
  "statusCode": 404
}
```

| Field        | Description                                    |
| ------------ | ---------------------------------------------- |
| `error`      | Short error label                              |
| `message`    | Human-readable description                     |
| `statusCode` | HTTP status code (mirrors the response status) |

## Status codes

| Code  | Meaning                                                               |
| ----- | --------------------------------------------------------------------- |
| `200` | Success                                                               |
| `201` | Resource created                                                      |
| `400` | Bad request: invalid or missing parameters                            |
| `401` | Unauthorized: missing or invalid session token                        |
| `403` | Forbidden: authenticated but insufficient role                        |
| `404` | Not found: resource doesn't exist or is outside your org              |
| `409` | Conflict: duplicate resource (e.g. duplicate `skillId` within an org) |
| `422` | Unprocessable: validation failed (Joi schema rejection)               |
| `500` | Internal server error                                                 |

## Authorization errors

`401` and `403` are distinct:

* `401` means no valid session token was provided
* `403` means the token is valid but the user's role doesn't permit the action

Both indicate an auth failure but require different handling: `401` should trigger a re-auth flow, while `403` is a permission issue that re-auth won't fix.