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

# Códigos de erro

> Entenda os códigos HTTP da Sorsa API, suas causas e como resolver erros de 400 a 500.

Quando uma requisição falha, a Sorsa retorna um código HTTP e um corpo JSON com `message` descrevendo o problema.

## Formato de erro

```json theme={null}
{
  "message": "ApiKey required"
}
```

O campo `message` contém uma descrição legível. Consulte-o primeiro ao investigar uma falha.

## Referência rápida

| Código | Tipo             | Significado                           |
| :----- | :--------------- | :------------------------------------ |
| 200    | Sucesso          | Requisição concluída                  |
| 400    | Erro do cliente  | Parâmetros inválidos ou ausentes      |
| 401    | Erro do cliente  | Falha na autenticação                 |
| 403    | Erro do cliente  | Chave válida, mas sem acesso ou saldo |
| 404    | Erro do cliente  | Recurso inexistente ou privado        |
| 429    | Erro do cliente  | Limite de requisições excedido        |
| 500    | Erro do servidor | Falha interna                         |

## 400 Bad Request

A requisição contém parâmetros inválidos ou ausentes.

**Causas comuns:** ausência de `link`, `id`, `username` ou `query` obrigatório; tipo ou formato incorreto; corpo JSON vazio ou malformado em POST.

**Solução:** confira os campos na [referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide). Em POST, use `Content-Type: application/json` e um corpo JSON válido.

## 401 Unauthorized

A API não conseguiu autenticar sua conta.

**Causas comuns:** cabeçalho `ApiKey` ausente ou incorreto; chave inválida, excluída ou copiada com espaços. Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas, mas `Api-Key` e `api_key` são nomes diferentes.

**Solução:** envie `ApiKey: your_key_here` e confirme que a chave está ativa no [painel](https://api.sorsa.io/overview/keys). Se necessário, copie-a novamente. Veja [autenticação](https://docs.sorsa.io/pt-BR/authentication).

## 403 Forbidden

A chave é válida, mas a requisição foi rejeitada. A cota pode ter acabado ou a assinatura expirado.

**Solução:** consulte `GET /key-usage-info` ou o [painel](https://api.sorsa.io/overview). Recarregue o saldo ou altere o plano em [Billing](https://api.sorsa.io/overview/billing).

## 404 Not Found

O recurso não existe ou não está acessível.

**Causas comuns:** nome de usuário alterado, conta excluída ou suspensa, publicação excluída, conta ou publicação protegida, ou URL incorreta. A Sorsa acessa apenas dados públicos.

**Solução:** confirme que o recurso ainda existe e é público no X. IDs de usuários permanecem estáveis após mudanças de nome. Com um ID salvo, consulte `/id-to-username/{user_id}` ou use `user_id` diretamente nos endpoints compatíveis.

## 429 Too Many Requests

O limite de 20 requisições por segundo foi excedido, normalmente por loops sem espera ou workers paralelos com a mesma chave.

**Solução:** uma pausa de 50 ms controla um worker sequencial; chaves compartilhadas exigem coordenação. Outra opção é repetir após uma pausa de um segundo. Veja [limites de requisições](https://docs.sorsa.io/pt-BR/rate-limits).

## 500 Internal Server Error

Houve uma falha interna.

* Tente novamente após 1 a 2 segundos; falhas transitórias costumam desaparecer.
* Se persistir ou afetar vários endpoints, consulte a [página de status](https://uptime.sorsa.io/status/v3).
* Procure [contacts@sorsa.io](mailto:contacts@sorsa.io) ou o [Discord](https://discord.com/invite/uwAefKCj7X), informando URL, corpo da requisição e horário aproximado. Remova chaves e cabeçalhos de autorização dos diagnósticos.

## Tratamento de erros no código

Estes padrões reutilizáveis evitam que uma resposta inesperada interrompa a integração sem tratamento.

**Python**

```python theme={null}
import time
import requests

def sorsa_request(method, endpoint, api_key, params=None, json_body=None, max_attempts=3):
    """GET/POST data retrieval with bounded retries; max_attempts includes the first call."""
    method = method.upper()
    if method not in {"GET", "POST"}:
        raise ValueError("Use GET or POST")
    if max_attempts < 1:
        raise ValueError("max_attempts must be positive")
    url = f"https://api.sorsa.io/v3{endpoint}"

    for attempt in range(max_attempts):
        try:
            response = requests.request(
                method, url, headers={"ApiKey": api_key},
                params=params, json=json_body, timeout=30,
            )
        except (requests.Timeout, requests.ConnectionError):
            if attempt + 1 == max_attempts:
                raise
        else:
            if response.ok:
                return response.json()
            retryable = response.status_code == 429 or response.status_code >= 500
            if not retryable or attempt + 1 == max_attempts:
                try:
                    message = response.json().get("message", response.reason)
                except (ValueError, AttributeError):
                    message = response.reason
                raise requests.HTTPError(
                    f"HTTP {response.status_code}: {message}", response=response,
                )
        time.sleep(min(2 ** attempt, 8))

data = sorsa_request("GET", "/info", "YOUR_API_KEY", params={"username": "elonmusk"})
print(data["display_name"])
```

**JavaScript**

```javascript theme={null}
async function sorsaRequest(method, endpoint, apiKey, body = null, maxAttempts = 3) {
  method = method.toUpperCase();
  if (!["GET", "POST"].includes(method)) throw new Error("Use GET or POST");
  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
    throw new Error("maxAttempts must be a positive integer");
  }
  if (method === "GET" && body !== null) throw new Error("Use query parameters for GET");
  const url = `https://api.sorsa.io/v3${endpoint}`;
  const options = { method, headers: { ApiKey: apiKey } };
  if (body !== null) {
    options.headers["Content-Type"] = "application/json";
    options.body = JSON.stringify(body);
  }

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    let response;
    try {
      response = await fetch(url, { ...options, signal: AbortSignal.timeout(30000) });
    } catch (error) {
      if (attempt + 1 === maxAttempts) throw error;
      await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 8) * 1000));
      continue;
    }
    if (response.ok) return await response.json();
    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt + 1 === maxAttempts) {
      let message = response.statusText;
      try { message = (await response.json()).message || message; } catch {}
      throw new Error(`HTTP ${response.status}: ${message}`);
    }
    await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 8) * 1000));
  }
}

const data = await sorsaRequest("GET", "/info?username=elonmusk", "YOUR_API_KEY");
console.log(data.display_name);
```

Os exemplos repetem timeouts, falhas de conexão, `429` e `5xx`, com no máximo três tentativas por padrão. Outros erros HTTP falham imediatamente. Respostas de sucesso com JSON inválido também geram erro para investigação. Use Node.js 18+ e instale `requests` no Python.

## Próximos passos

* [Limites de requisições](https://docs.sorsa.io/pt-BR/rate-limits): estratégias para 20 req/s.
* [Paginação](https://docs.sorsa.io/pt-BR/pagination): coleta de grandes conjuntos.
* [Referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide): endpoints e parâmetros.