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.

Guía de API

Referencia de API

Integraciones

Protocolo de Contexto de Modelo (MCP)

Códigos de Estado HTTP

Tipos de Error y Ejemplos

Errores de Autenticación (403)

Errores de Validación (400)

Errores de Límite de Tasa (429)

Errores del Servidor (500)

Header de workspace ausente (422)

​Códigos de Estado HTTP

​Tipos de Error y Ejemplos

​Errores de Autenticación (403)

​Errores de Validación (400)

​Errores de Límite de Tasa (429)

​Errores del Servidor (500)

​Header de workspace ausente (422)

Códigos de Estado HTTP

Tipos de Error y Ejemplos

Errores de Autenticación (403)

Errores de Validación (400)

Errores de Límite de Tasa (429)

Errores del Servidor (500)

Header de workspace ausente (422)