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

# Errors

The Tess AI API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

* Codes in the `2xx` range indicate success
* Codes in the `4xx` range indicate an error that failed given the information provided
* Codes in the `5xx` range indicate an error with our servers (these are rare)

## **HTTP Status Codes**

| **Status Code** | **Description**                                                      | **Common Causes**                                                                 |
| :-------------- | :------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| 200             | Success - The request was successful                                 | Request completed as expected                                                     |
| 201             | Created - The resource was successfully created                      | New webhook created successfully                                                  |
| 400             | Bad Request - The request was invalid                                | Missing required fields, invalid parameter values                                 |
| 403             | Forbidden - Authentication failed                                    | Invalid API key, expired token, insufficient permissions                          |
| 413             | Payload Too Large - Request body exceeds allowed size                | File exceeds maximum upload size                                                  |
| 422             | Unprocessable Entity - Required workspace context missing or invalid | Missing `x-workspace-id` header (required as of 2026-09-01), invalid workspace id |
| 429             | Rate Limited - Too many requests                                     | Exceeded API rate limits                                                          |
| 500             | Internal Server Error - Server issue                                 | Unexpected server error (please contact support)                                  |

## **Error Types and Examples**

### **Authentication Errors (403)**

These errors occur when there's a problem with your API key:

```
{
  "error": "Invalid authentication"
}
```

Common causes:

* Invalid API key
* Expired API key
* Missing Authorization header
* Insufficient permissions

### **Validation Errors (400)**

Occur when the request data doesn't meet the requirements:

```
{
  "error": "Validation failed",
  "messages": {
    "url": ["The url field must be a valid HTTPS URL"],
    "method": ["The method must be one of: POST, GET"]
  }
}
```

Common validation rules:

* **Webhooks**
  * URL must be a valid HTTPS URL
  * Method must be either POST or GET
  * Status must be either "active" or "inactive"
* **Files**
  * File must be provided for upload
  * Process flag is optional (default: false)

### **Missing workspace header (422)**

As of **2026-09-01**, authenticated API requests must include `x-workspace-id`. If the header is missing:

```
{
  "message": "The x-workspace-id header is required."
}
```

Until that date, omitting the header falls back to the user's selected workspace (deprecated). Send `x-workspace-id` on every request to stay compatible.

### **Rate Limit Errors (429)**

Occur when you've exceeded the API rate limits:

```
{
  "error": "Rate limit exceeded",
  "retry_after": 60
}
```

### **Server Errors (500)**

Indicate an issue on our end:

```
{
  "error": "Internal server error"
}
```