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

# Errors

> Understand how the Caspen API reports problems and the status codes you might encounter

## Overview

Caspen uses conventional HTTP status codes to describe request outcomes:

* Codes in the `2xx` range indicate success.
* Codes in the `4xx` range indicate an issue with the request.
* Codes in the `5xx` range indicate a server-side problem.

HTTP status codes communicate the category of the problem, and the JSON body provides the platform-formatted message (with field-level errors when validation fails).

## HTTP status codes

### 2xx - Success

| Code  | Status     | Description                                 |
| ----- | ---------- | ------------------------------------------- |
| `200` | OK         | The request succeeded                       |
| `201` | Created    | A new resource was created                  |
| `204` | No Content | The operation succeeded and returns no body |

### 4xx - Client errors

| Code  | Status               | Description                                            |
| ----- | -------------------- | ------------------------------------------------------ |
| `400` | Bad Request          | The request cannot be processed (generic client error) |
| `401` | Unauthorized         | Missing or invalid bearer token                        |
| `403` | Forbidden            | Authenticated but not allowed to perform this action   |
| `404` | Not Found            | The requested resource does not exist                  |
| `409` | Conflict             | The request conflicts with the current resource state  |
| `422` | Unprocessable Entity | Validation failed; see the `errors` object for details |
| `429` | Too Many Requests    | Rate limit exceeded                                    |

### 5xx - Server errors

| Code  | Status                | Description                                      |
| ----- | --------------------- | ------------------------------------------------ |
| `500` | Internal Server Error | An unexpected error occurred                     |
| `502` | Bad Gateway           | Upstream dependency returned an invalid response |
| `503` | Service Unavailable   | The service is temporarily unavailable           |