> ## 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

La API de Tess AI utiliza códigos de respuesta HTTP convencionales para indicar el éxito o fallo de una solicitud de API. En general:

* Los códigos en el rango `2xx` indican éxito
* Los códigos en el rango `4xx` indican un error que falló con la información proporcionada
* Los códigos en el rango `5xx` indican un error con nuestros servidores (estos son raros)

## **Códigos de Estado HTTP**

| **Código de Estado** | **Descripción**                                                 | **Causas Comunes**                                                                         |
| :------------------- | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
| 200                  | Éxito - La solicitud fue exitosa                                | Solicitud completada como se esperaba                                                      |
| 201                  | Creado - El recurso se creó exitosamente                        | Nuevo webhook creado exitosamente                                                          |
| 400                  | Solicitud Incorrecta - La solicitud era inválida                | Campos obligatorios faltantes, valores de parámetros inválidos                             |
| 403                  | Prohibido - La autenticación falló                              | Clave de API inválida, token expirado, permisos insuficientes                              |
| 422                  | Unprocessable Entity - Contexto de workspace ausente o inválido | Header `x-workspace-id` ausente (obligatorio a partir del 01/09/2026) o workspace inválido |
| 429                  | Límite de Tasa - Demasiadas solicitudes                         | Límites de tasa de API excedidos                                                           |
| 500                  | Error Interno del Servidor - Problema del servidor              | Error inesperado del servidor (por favor contacta al soporte)                              |

## **Tipos de Error y Ejemplos**

### **Errores de Autenticación (403)**

Estos errores ocurren cuando hay un problema con tu clave de API:

```
{
  "error": "Autenticación inválida"
}
```

Causas comunes:

* Clave de API inválida
* Clave de API expirada
* Encabezado Authorization faltante
* Permisos insuficientes

### **Errores de Validación (400)**

Ocurren cuando los datos de la solicitud no cumplen con los requisitos:

```
{
  "error": "Validación fallida",
  "messages": {
    "url": ["El campo url debe ser una URL HTTPS válida"],
    "method": ["El método debe ser uno de: POST, GET"]
  }
}
```

Reglas de validación comunes:

* **Webhooks**
  * URL debe ser una URL HTTPS válida
  * Método debe ser POST o GET
  * Estado debe ser "active" o "inactive"
* **Archivos**
  * Archivo debe ser proporcionado para carga
  * Bandera de procesamiento es opcional (predeterminado: false)

### **Errores de Límite de Tasa (429)**

Ocurren cuando has excedido los límites de tasa de la API:

```
{
  "error": "Límite de tasa excedido",
  "retry_after": 60
}
```

### **Errores del Servidor (500)**

Indican un problema de nuestro lado:

```
{
  "error": "Error interno del servidor"
}
```

### **Header de workspace ausente (422)**

A partir del **01/09/2026**, las solicitudes autenticadas de la API deben incluir `x-workspace-id`. Si el header está ausente:

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

Hasta esa fecha, omitir el header usa el workspace seleccionado del usuario (deprecated). Envía `x-workspace-id` en cada solicitud para mantener la compatibilidad.