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

# Errors & Status Codes

> Standard error format and error code reference

When an API request fails, IllumiChat returns a structured error response with an HTTP status code, a human-readable message, and a machine-readable error code.

## Error Response Format

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "error_type:context"
}
```

| Field   | Type     | Description                                                          |
| ------- | -------- | -------------------------------------------------------------------- |
| `error` | `string` | A message suitable for displaying to users or logging                |
| `code`  | `string` | A structured code in `type:context` format for programmatic handling |

### Validation Errors

Some endpoints return field-level details when validation fails:

```json theme={null}
{
  "error": "Validation failed",
  "code": "bad_request:api",
  "details": {
    "name": "Name is required",
    "email": "Invalid email format"
  }
}
```

## HTTP Status Codes

| Code  | Meaning                   | Description                                        |
| ----- | ------------------------- | -------------------------------------------------- |
| `200` | **OK**                    | Successful `GET`, `PATCH`, or `DELETE` request     |
| `201` | **Created**               | Successful `POST` request that created a resource  |
| `400` | **Bad Request**           | Validation failed or required fields are missing   |
| `401` | **Unauthorized**          | Not authenticated -- session is missing or expired |
| `403` | **Forbidden**             | Authenticated but insufficient permissions         |
| `404` | **Not Found**             | The requested resource does not exist              |
| `409` | **Conflict**              | Resource already exists (e.g., duplicate name)     |
| `429` | **Too Many Requests**     | Rate limit exceeded                                |
| `500` | **Internal Server Error** | An unexpected error occurred on the server         |

## Error Code Reference

### Authentication & Authorization

| Code                  | HTTP Status | Description                                |
| --------------------- | ----------- | ------------------------------------------ |
| `unauthorized:api`    | `401`       | Not authenticated for an API operation     |
| `unauthorized:chat`   | `401`       | Not authenticated for a chat operation     |
| `unauthorized:widget` | `401`       | Not authenticated for a widget operation   |
| `forbidden:api`       | `403`       | Insufficient permissions for the operation |

### Request Errors

| Code               | HTTP Status | Description                                  |
| ------------------ | ----------- | -------------------------------------------- |
| `bad_request:api`  | `400`       | Invalid request parameters or missing fields |
| `bad_request:chat` | `400`       | Invalid chat request                         |
| `not_found:api`    | `404`       | Requested resource was not found             |
| `not_found:chat`   | `404`       | Chat conversation not found                  |
| `not_found:widget` | `404`       | Widget configuration not found               |
| `conflict:api`     | `409`       | Resource conflict such as a duplicate entry  |

### Billing & Quota Errors

| Code                     | HTTP Status | Description                                                                                                                                                                     |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credits_limit_exceeded` | `403`       | The workspace has used all of its monthly credits. Chat is blocked until credits reset (monthly) or the workspace upgrades. See [Plans & credits](/account#subscription-plans). |

### Rate Limit Errors

| Code                | HTTP Status | Description                         |
| ------------------- | ----------- | ----------------------------------- |
| `rate_limit:widget` | `429`       | Widget endpoint rate limit exceeded |

### Server Errors

| Code                        | HTTP Status | Description                  |
| --------------------------- | ----------- | ---------------------------- |
| `internal_server_error:api` | `500`       | Unexpected server-side error |

## Handling Errors

### Check the HTTP status code first

```javascript theme={null}
const response = await fetch("https://app.illumichat.com/api/assistants", {
  credentials: "include",
});

if (!response.ok) {
  const { error, code } = await response.json();

  switch (response.status) {
    case 401:
      window.location.href = "/login";
      break;
    case 403:
      showError("You don't have access to this resource.");
      break;
    case 429:
      await delay(getBackoffMs(retryCount));
      break;
    default:
      console.error(`API error [${code}]: ${error}`);
      showError(error);
  }
}
```

### Use the `code` field for programmatic handling

The `code` field is a stable identifier you can match against, while the `error` message may change.

```javascript theme={null}
if (code === "not_found:chat") {
  router.push("/chats");
} else if (code === "forbidden:api") {
  showUpgradePrompt();
}
```

### Handle 429s with exponential backoff

```javascript theme={null}
function getBackoffMs(retryCount) {
  return Math.min(1000 * Math.pow(2, retryCount), 30000);
}
```

<Tip>
  Log the full error response (including `code` and `details`) to make debugging easier during development.
</Tip>