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

# Erros e Limites

> Formato de erro, códigos comuns, limites de taxa e status do serviço

<Warning>
  Rascunho: especificação em definição. Endpoints e campos podem mudar.
</Warning>

## Formato de erro

A API usa os status HTTP convencionais e devolve sempre o mesmo corpo em caso de erro:

```json theme={null}
{
  "erro": {
    "codigo": "saldo_insuficiente",
    "mensagem": "O valor solicitado excede o saldo disponível para resgate.",
    "campo": "valor",
    "requisicao_id": "req_9d8c7b"
  }
}
```

| Campo | Descrição |
| - | - |
| `codigo` | Código estável, próprio para tratamento no código da integração |
| `mensagem` | Texto legível, que pode mudar sem aviso |
| `campo` | Campo da requisição que causou o erro, quando houver |
| `requisicao_id` | Identificador para suporte. Inclua esse valor ao escrever para [contact@t3sa.com](mailto:contact@t3sa.com) |

## Códigos comuns

| HTTP | Código | Quando acontece |
| - | - | - |
| `400` | `requisicao_invalida` | Corpo malformado ou parâmetro ausente |
| `401` | `nao_autenticado` | Chave ausente, inválida ou revogada |
| `401` | `assinatura_invalida` | HMAC não confere ou timestamp fora da janela de 5 minutos |
| `403` | `escopo_insuficiente` | A chave não tem o escopo exigido pelo endpoint |
| `403` | `ip_nao_autorizado` | IP de origem fora da allowlist da chave |
| `404` | `nao_encontrado` | Recurso inexistente ou de outra organização |
| `409` | `conflito_idempotencia` | `Idempotency-Key` repetida com corpo diferente |
| `409` | `estado_invalido` | Ação incompatível com o status atual, como aprovar uma proposta já rejeitada |
| `422` | `politica_invalida` | Percentuais da política não fecham em 100 ou incluem ativo não suportado |
| `422` | `saldo_insuficiente` | Resgate acima do saldo disponível |
| `422` | `carteira_nao_vinculada` | Destino do resgate não é uma carteira vinculada da empresa |
| `429` | `limite_excedido` | Limite de taxa atingido |
| `500` | `erro_interno` | Falha do lado da TESA |
| `503` | `servico_indisponivel` | Manutenção ou dependência externa indisponível, como pausa no CCTP da Circle |

<Note>
  Erros `5xx` e `429` podem ser repetidos com espera crescente. Em `POST`, repita com a mesma `Idempotency-Key` para não duplicar a operação.
</Note>

## Limites de taxa

Os valores abaixo são uma proposta inicial, por chave de API:

| Tipo de requisição | Limite proposto |
| - | - |
| Leitura (`GET`) | 300 requisições por minuto |
| Escrita (`POST`, `PUT`) | 30 requisições por minuto |
| Sandbox | Metade dos limites de produção |

Toda resposta traz os cabeçalhos abaixo. Ao receber `429`, respeite o cabeçalho `Retry-After`, em segundos.

| Cabeçalho | Conteúdo |
| - | - |
| `RateLimit-Limit` | Limite da janela atual |
| `RateLimit-Remaining` | Requisições restantes na janela |
| `RateLimit-Reset` | Segundos até a janela reiniciar |

Organizações no plano enterprise podem combinar limites maiores.

## Status do serviço

A proposta é publicar uma página de status em `https://status.t3sa.com` (endereço provisório, ainda não ativo), com a disponibilidade da API, dos webhooks e das dependências externas, como o CCTP da Circle e os emissores de USDY e BUIDL.