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": "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:
{
"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 |
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
const response = await fetch("https://beta.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.
if (code === "not_found:chat") {
router.push("/chats");
} else if (code === "forbidden:api") {
showUpgradePrompt();
}
Handle 429s with exponential backoff
function getBackoffMs(retryCount) {
return Math.min(1000 * Math.pow(2, retryCount), 30000);
}
Log the full error response (including code and details) to make debugging easier during development.
