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

A API da Tess AI usa códigos de resposta HTTP convencionais para indicar o sucesso ou a falha de uma requisição. Em geral:

* Códigos na faixa `2xx` indicam sucesso
* Códigos na faixa `4xx` indicam um erro causado pelas informações fornecidas
* Códigos na faixa `5xx` indicam um erro nos nossos servidores (esses são raros)

## **Códigos de Status HTTP**

| **Código de Status** | **Descrição**                                                        | **Causas Comuns**                                                                          |
| :------------------- | :------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
| 200                  | Success - A requisição foi bem-sucedida                              | Requisição concluída conforme esperado                                                     |
| 201                  | Created - O recurso foi criado com sucesso                           | Novo webhook criado com sucesso                                                            |
| 400                  | Bad Request - A requisição era inválida                              | Campos obrigatórios ausentes, valores de parâmetro inválidos                               |
| 403                  | Forbidden - Falha na autenticação                                    | Chave de API inválida, token expirado, permissões insuficientes                            |
| 413                  | Payload Too Large - O corpo da requisição excede o tamanho permitido | Arquivo excede o tamanho máximo de upload                                                  |
| 422                  | Unprocessable Entity - Contexto de workspace ausente ou inválido     | Header `x-workspace-id` ausente (obrigatório a partir de 01/09/2026) ou workspace inválido |
| 429                  | Rate Limited - Muitas requisições                                    | Rate limits da API excedidos                                                               |
| 500                  | Internal Server Error - Problema no servidor                         | Erro inesperado no servidor (entre em contato com o suporte)                               |

## **Tipos de Erros e Exemplos**

### **Erros de Autenticação (403)**

Esses erros ocorrem quando há um problema com sua chave de API:

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

Causas comuns:

* Chave de API inválida
* Chave de API expirada
* Header de Authorization ausente
* Permissões insuficientes

### **Erros de Validação (400)**

Ocorrem quando os dados da requisição não atendem aos requisitos:

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

Regras de validação comuns:

* **Webhooks**
  * A URL deve ser uma URL HTTPS válida
  * O método deve ser POST ou GET
  * O status deve ser "active" ou "inactive"
* **Arquivos**
  * O arquivo deve ser fornecido para upload
  * O flag de processamento é opcional (padrão: false)

### **Erros de Rate Limit (429)**

Ocorrem quando você excedeu os rate limits da API:

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

### **Erros de Servidor (500)**

Indicam um problema no nosso lado:

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

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

A partir de **01/09/2026**, requisições autenticadas da API devem incluir `x-workspace-id`. Se o header estiver ausente:

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

Até essa data, omitir o header usa o workspace selecionado do usuário (deprecated). Envie `x-workspace-id` em toda requisição para manter a compatibilidade.