Errors and Limits

Draft: specification in progress. Endpoints and fields may change.

Error format

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

{
  "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

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

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

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.

Getting started

Guides

Reference

API reference

Error format

Common codes

Rate limits

Service status

​Error format

​Common codes

​Rate limits

​Service status

Error format

Common codes

Rate limits

Service status