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

# Error Responses and Status Codes Reference

> CA Colombia API returns structured JSON errors. Understand HTTP status codes, error codes, and how to handle authentication and validation failures.

Every error response from the CA Colombia API returns a JSON body containing at least an `error` field with a human-readable message. Many errors also include a `code` field that identifies the specific failure condition, and validation errors add a `details` array with field-level information. You should always check both `error` and `code` when building error-handling logic in your application.

## Error Response Shape

```json theme={null}
{
  "error": "Unauthorized",
  "code": "INVALID_TOKEN"
}
```

For validation failures, a `details` array is included alongside the `error` field:

```json theme={null}
{
  "error": "Invalid form of body",
  "details": [
    {
      "path": ["firstNames"],
      "message": "First name too short"
    }
  ]
}
```

***

## HTTP Status Codes

The API uses standard HTTP status codes to communicate the outcome of every request. The table below describes what each code means in the context of CA Colombia.

| Status | Meaning                                                                                |
| ------ | -------------------------------------------------------------------------------------- |
| `200`  | The request succeeded and a response body is returned.                                 |
| `201`  | The request succeeded and a new resource was created.                                  |
| `304`  | Not Modified — the resource was already in the requested state and no change was made. |
| `400`  | The request body or query parameters are invalid or malformed.                         |
| `401`  | Unauthenticated — no valid session cookie was found or the token is invalid.           |
| `403`  | Forbidden — your session is valid, but you do not have the required permissions.       |
| `404`  | The requested resource was not found.                                                  |
| `409`  | Conflict — for example, your character limit has been exceeded.                        |
| `429`  | Rate limited — you have exceeded the allowed number of requests for this window.       |
| `500`  | Internal server error — an unexpected failure occurred on the server.                  |

***

## Authentication Error Codes

When a `401` or `403` response is returned, the `code` field contains a machine-readable identifier. Use these codes to distinguish between different authentication failure states and respond accordingly in your application.

| Code                           | HTTP Status | Meaning                                                                                      |
| ------------------------------ | ----------- | -------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`              | `401`       | No session cookie was present on the request.                                                |
| `INVALID_TOKEN_STRUCTURE`      | `401`       | The session cookie is present but its format is malformed.                                   |
| `FAILED_TOKEN_UID_PARSE`       | `401`       | The user ID encoded in the token could not be decoded.                                       |
| `INVALID_TOKEN`                | `401`       | The token was not found in the database — it may be expired or compromised.                  |
| `FAILED_TOKEN_UID_MISSMATCH`   | `401`       | The user ID embedded in the token does not match the token record.                           |
| `USER_NOT_FOUND`               | `401`       | The token is structurally valid but the associated user no longer exists.                    |
| `FAILED_TOKEN_PARSE_MISSMATCH` | `401`       | The access token and refresh token could not both be parsed during a renewal attempt.        |
| `MISSING_FULL_PERMISSIONS`     | `403`       | Your account is missing all of the required permissions for this endpoint.                   |
| `MISSING_PARTIAL_PERMISSIONS`  | `403`       | Your account is missing at least one of the required permissions for this endpoint.          |
| `FAILED_TOKEN_RENEWAL`         | `401`       | Your session token was expired and the server could not refresh it using your refresh token. |
| `FAILED_TOKEN_PARSING`         | `401`       | The token could not be parsed — catch-all for unexpected token errors.                       |

<Note>
  When `INVALID_TOKEN` is returned, the API automatically clears your session cookies. You will need to re-authenticate before making further requests.
</Note>

***

## Validation Errors

When you submit a request body that fails schema validation, the API returns a `400` response with `"error": "Invalid form of body"` and a `details` array. Each entry in the array corresponds to a specific field that failed validation.

**Example — creating a character with a missing field:**

```json theme={null}
{
  "error": "Invalid form of body",
  "details": [
    {
      "path": ["firstNames"],
      "message": "First name too short"
    },
    {
      "path": ["dob"],
      "message": "Invalid dob"
    }
  ]
}
```

Each object in `details` contains:

* **`path`** — an array of strings indicating which field or nested key failed. For top-level fields this is a single-element array, e.g. `["firstNames"]`.
* **`message`** — a human-readable description of why the field failed validation.

<Tip>
  Iterate over the `details` array to surface field-specific messages directly in your UI, rather than displaying the top-level `error` string alone.
</Tip>

***

## Other Common Error Responses

| Error message                         | Typical status | When it occurs                                                                |
| ------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `"The resource was not found"`        | `404`          | A generic resource look-up returned nothing.                                  |
| `"Unknown User"`                      | `404`          | The requested user ID does not exist.                                         |
| `"Unknown Character"`                 | `404`          | The requested character ID does not exist.                                    |
| `"User Max Character Limit Exceeded"` | `409`          | You have reached the maximum number of characters allowed on your account.    |
| `"Internal Server Error"`             | `500`          | An unexpected error occurred. Check the optional `message` field for details. |

<Warning>
  `500` responses may include a `message` field with additional context, but this is not guaranteed. Do not rely on its presence in production error-handling code.
</Warning>