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

# Erros

> Códigos de erro e como tratá-los na API do Talk AI.

## Formato de erro

Todos os erros seguem o mesmo formato JSON:

```json theme={null}
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}
```

## Códigos HTTP

| Código | Significado              | Quando ocorre                         |
| ------ | ------------------------ | ------------------------------------- |
| `200`  | Sucesso                  | Requisição processada corretamente    |
| `401`  | Não autorizado           | API key ausente, inválida ou expirada |
| `403`  | Proibido                 | Assinatura da empresa inativa         |
| `422`  | Entidade não processável | Corpo da requisição inválido          |
| `500`  | Erro interno             | Erro inesperado no servidor           |

## Erros de autenticação (401)

```json theme={null}
// API key ausente
{ "statusCode": 401, "error": "Unauthorized", "message": "Missing API key" }

// Formato inválido
{ "statusCode": 401, "error": "Unauthorized", "message": "Invalid API key format. Expected: Bearer <api_key>" }

// Chave inválida ou expirada
{ "statusCode": 401, "error": "Unauthorized", "message": "Invalid or expired API key" }
```

## Erro de assinatura (403)

```json theme={null}
{
  "statusCode": 403,
  "error": "SubscriptionInactive",
  "message": "Sua assinatura não está ativa",
  "subscriptionStatus": "CANCELLED"
}
```

## Erros de validação (422)

```json theme={null}
{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": [
    "queryText must be a string",
    "scoreThreshold must not be greater than 1"
  ]
}
```

## Tratamento de erros

<CodeGroup>
  ```javascript Node.js theme={null}
  async function ragRetrieve(query) {
    const response = await fetch('https://api-talk.saninternet.com/v1/api/rag/retrieve', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SANTALK_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        queryText: query,
        filters: { sourceTypes: ['document'], audience: 'ai_agent' },
        scoreThreshold: 0.7,
        returnMode: 'ai_generated_answer'
      })
    });

    if (!response.ok) {
      const error = await response.json();
      switch (response.status) {
        case 401: throw new Error(`Autenticação falhou: ${error.message}`);
        case 403: throw new Error(`Assinatura inativa: ${error.subscriptionStatus}`);
        case 422: throw new Error(`Validação: ${error.message}`);
        default: throw new Error(`Erro ${response.status}: ${error.message}`);
      }
    }

    return response.json();
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  def rag_retrieve(query: str) -> dict:
      response = requests.post(
          'https://api-talk.saninternet.com/v1/api/rag/retrieve',
          headers={
              'Authorization': f'Bearer {os.environ["SANTALK_API_KEY"]}',
              'Content-Type': 'application/json'
          },
          json={
              'queryText': query,
              'filters': {'sourceTypes': ['document'], 'audience': 'ai_agent'},
              'scoreThreshold': 0.7,
              'returnMode': 'ai_generated_answer'
          }
      )

      if response.status_code == 401:
          raise Exception(f"Autenticação falhou: {response.json()['message']}")
      elif response.status_code == 403:
          raise Exception(f"Assinatura inativa: {response.json()['subscriptionStatus']}")

      response.raise_for_status()
      return response.json()
  ```
</CodeGroup>