Errores y límites

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:

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

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

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.

Para comenzar

Guías

Referencia

Referencia de la API

Errores y límites

Formato de error

Códigos comunes

Límites de tasa

Estado del servicio