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

# Errors and Limits

> Error format, common codes, rate limits and service status

<Warning>
  Draft: specification in progress. Endpoints and fields may change.
</Warning>

## Error format

The API uses conventional HTTP status codes and always returns the same body on error:

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

| Field | Description |
| - | - |
| `codigo` | Stable code, suitable for handling in your integration's code |
| `mensagem` | Human-readable text, which may change without notice |
| `campo` | The request field that caused the error, when applicable |
| `requisicao_id` | Identifier for support. Include this value when writing to [contact@t3sa.com](mailto:contact@t3sa.com) |

## Common codes

| HTTP | Code | When it happens |
| - | - | - |
| `400` | `requisicao_invalida` | Malformed body or missing parameter |
| `401` | `nao_autenticado` | Missing, invalid or revoked key |
| `401` | `assinatura_invalida` | HMAC does not match or timestamp is outside the 5-minute window |
| `403` | `escopo_insuficiente` | The key lacks the scope required by the endpoint |
| `403` | `ip_nao_autorizado` | Source IP outside the key's allowlist |
| `404` | `nao_encontrado` | Resource does not exist or belongs to another organization |
| `409` | `conflito_idempotencia` | `Idempotency-Key` reused with a different body |
| `409` | `estado_invalido` | Action incompatible with the current status, such as approving an already rejected proposal |
| `422` | `politica_invalida` | Policy percentages do not add up to 100 or include an unsupported asset |
| `422` | `saldo_insuficiente` | Redemption above the available balance |
| `422` | `carteira_nao_vinculada` | Redemption destination is not a linked company wallet |
| `429` | `limite_excedido` | Rate limit reached |
| `500` | `erro_interno` | Failure on TESA's side |
| `503` | `servico_indisponivel` | Maintenance or an external dependency is unavailable, such as a pause in Circle's CCTP |

<Note>
  `5xx` and `429` errors can be retried with increasing backoff. For `POST`, retry with the same `Idempotency-Key` to avoid duplicating the operation.
</Note>

## Rate limits

The values below are an initial proposal, per API key:

| Request type | Proposed limit |
| - | - |
| Read (`GET`) | 300 requests per minute |
| Write (`POST`, `PUT`) | 30 requests per minute |
| Sandbox | Half of the production limits |

Every response includes the headers below. When you receive a `429`, honor the `Retry-After` header, in seconds.

| Header | Content |
| - | - |
| `RateLimit-Limit` | Limit for the current window |
| `RateLimit-Remaining` | Requests remaining in the window |
| `RateLimit-Reset` | Seconds until the window resets |

Organizations on the enterprise plan can agree on higher limits.

## Service status

The proposal is to publish a status page at `https://status.t3sa.com` (provisional address, not live yet), showing the availability of the API, webhooks and external dependencies, such as Circle's CCTP and the USDY and BUIDL issuers.