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

# Errores y límites

> Formato de error, códigos comunes, límites de tasa y estado del servicio

> [!WARNING]
>
> Borrador: especificación en curso. Los endpoints y campos pueden cambiar.

## Formato de error

La API usa códigos de estado HTTP convencionales y siempre devuelve el mismo cuerpo en caso de 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"
  }
}
```

| Campo | Descripción |
| - | - |
| `codigo` | Código estable, adecuado para tratarlo en el código de su integración |
| `mensagem` | Texto legible por personas, que puede cambiar sin aviso |
| `campo` | El campo de la solicitud que causó el error, cuando corresponda |
| `requisicao_id` | Identificador para soporte. Inclúyalo al escribir a [contact@t3sa.com](mailto:contact@t3sa.com) |

## Códigos comunes

| HTTP | Código | Cuándo ocurre |
| - | - | - |
| `400` | `requisicao_invalida` | Cuerpo mal formado o parámetro ausente |
| `401` | `nao_autenticado` | Clave ausente, inválida o revocada |
| `401` | `assinatura_invalida` | El HMAC no coincide o la marca de tiempo está fuera de la ventana de 5 minutos |
| `403` | `escopo_insuficiente` | La clave no tiene el alcance que exige el endpoint |
| `403` | `ip_nao_autorizado` | IP de origen fuera de la lista permitida de la clave |
| `404` | `nao_encontrado` | El recurso no existe o pertenece a otra organización |
| `409` | `conflito_idempotencia` | `Idempotency-Key` reutilizada con un cuerpo distinto |
| `409` | `estado_invalido` | Acción incompatible con el estado actual, como aprobar una propuesta ya rechazada |
| `422` | `politica_invalida` | Los porcentajes de la política no suman 100 o incluyen un activo no compatible |
| `422` | `saldo_insuficiente` | Rescate por encima del saldo disponible |
| `422` | `carteira_nao_vinculada` | El destino del rescate no es una billetera vinculada de la empresa |
| `429` | `limite_excedido` | Se alcanzó el límite de tasa |
| `500` | `erro_interno` | Falla del lado de TESA |
| `503` | `servico_indisponivel` | Mantenimiento o dependencia externa no disponible, como una pausa del CCTP de Circle |

> [!NOTE]
>
> Los errores `5xx` y `429` pueden reintentarse con espera creciente. En los `POST`, reintente con la misma `Idempotency-Key` para evitar duplicar la operación.

## Límites de tasa

Los valores de abajo son una propuesta inicial, por clave de API:

| Tipo de solicitud | Límite propuesto |
| - | - |
| Lectura (`GET`) | 300 solicitudes por minuto |
| Escritura (`POST`, `PUT`) | 30 solicitudes por minuto |
| Sandbox | La mitad de los límites de producción |

Toda respuesta incluye los encabezados de abajo. Cuando reciba un `429`, respete el encabezado `Retry-After`, en segundos.

| Encabezado | Contenido |
| - | - |
| `RateLimit-Limit` | Límite de la ventana actual |
| `RateLimit-Remaining` | Solicitudes restantes en la ventana |
| `RateLimit-Reset` | Segundos hasta que se reinicie la ventana |

Las organizaciones en el plan Enterprise pueden acordar límites más altos.

## Estado del servicio

La propuesta es publicar una página de estado en `https://status.t3sa.com` (dirección provisoria, todavía no activa), que muestre la disponibilidad de la API, de los webhooks y de las dependencias externas, como el CCTP de Circle y los emisores de USDY y BUIDL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.