Erros e Limites

Rascunho: especificação em definição. Endpoints e campos podem mudar.

Formato de erro

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

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

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

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.

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.

Começando

Guias

Referência

Referência da API

Formato de erro

Códigos comuns

Limites de taxa

Status do serviço

​Formato de erro

​Códigos comuns

​Limites de taxa

​Status do serviço

Formato de erro

Códigos comuns

Limites de taxa

Status do serviço