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

# Error Handling

> Structured API error responses with HTTP status codes, ORPC error codes, and handling examples in JavaScript and Python

The Char API returns structured error responses with conventional HTTP status codes.

## Error Response Format

```json theme={null}
{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Invalid request data",
  "data": {
    "code": "VALIDATION_ERROR",
    "field": "name",
    "details": "Name is required"
  }
}
```

* `code` is the ORPC error code (HTTP-aligned)
* `data.code` is a machine-readable error identifier
* `data` may include additional fields depending on the error type

## Common Error Codes

| HTTP | ORPC Code               | data.code              | Notes                   |
| ---- | ----------------------- | ---------------------- | ----------------------- |
| 400  | `BAD_REQUEST`           | `VALIDATION_ERROR`     | Input validation failed |
| 401  | `UNAUTHORIZED`          | `AUTH_REQUIRED`        | Missing or invalid JWT  |
| 403  | `FORBIDDEN`             | `ACCESS_DENIED`        | Permission denied       |
| 403  | `ORG_CONTEXT_REQUIRED`  | `ORG_CONTEXT_REQUIRED` | Org context required    |
| 403  | `PAYMENT_REQUIRED`      | `PAYMENT_REQUIRED`     | Subscription required   |
| 404  | `NOT_FOUND`             | `RESOURCE_NOT_FOUND`   | Resource missing        |
| 409  | `CONFLICT`              | `DUPLICATE_RESOURCE`   | Resource already exists |
| 500  | `INTERNAL_SERVER_ERROR` | `INTERNAL_ERROR`       | Server error            |

## Handling Errors

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    async function listSkills(token) {
      const response = await fetch("https://app.usechar.ai/api/organization-skills/list", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${token}`,
        },
        body: JSON.stringify({ limit: 20, offset: 0 }),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`${error.code}: ${error.message}`);
      }

      return response.json();
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://app.usechar.ai/api/organization-skills/list",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        },
        json={"limit": 20, "offset": 0},
    )

    if response.status_code >= 400:
        error = response.json()
        raise Exception(f"{error['code']}: {error['message']}")

    data = response.json()
    ```
  </Tab>
</Tabs>

<Snippet file="support-cta.mdx" />