Ordem a Limite — status finais e retry
As rotas de ordem a limite estão ativas em Sandbox e em Produção. A funcionalidade
é habilitada por conta: sem a habilitação, a criação responde 403 com
Limit order is not enabled for this account.
Uma ordem a limite fica registrada e aberta (OPEN) e só executa quando o
mercado atinge o preço definido em limitPrice e está dentro da faixa de execução
da sua conta, dentro do prazo de validade (expiresAt / expiresInDays). Enquanto
isso não acontece, a ordem é avaliada a cada ciclo pelo motor de execução e permanece
aberta. Quando o preço é atingido, a ordem é executada por uma cotação RFQ criada
naquele momento — ver Execução por cotação RFQ.
Este guia explica como criar e cancelar uma ordem a limite pela API, os
dois desfechos de encerramento sem execução — EXPIRED e REJECTED — e a
política de retry (re-arm) que decide quando uma falha volta para a fila e
quando ela encerra a ordem de forma definitiva.
Como criar uma ordem a limite
Abra uma ordem a limite com createLimitOrder
(POST /orders/limit/orders). No corpo da requisição:
| Campo | Obrigatório? | O que é |
|---|---|---|
id | Sim | Chave de idempotência do cliente (client order id). Ver detalhe abaixo. |
profileId | Sim | Cliente (profile) dono da ordem. |
symbol | Sim | Par de negociação — ex.: BTC/BRL, ETH/BRL, USDC/BRL. |
side | Sim | buy (compra) ou sell (venda). |
limitPrice | Sim | Preço-alvo. Na compra executa quando o mercado cai até ele; na venda, quando sobe até ele — sempre dentro da faixa de execução da conta. |
quoteAmount ou amount | Sim | Tamanho da ordem, e o campo depende do lado: compra usa quoteAmount (valor na moeda de cotação); venda usa amount (quantidade na cripto). Ver abaixo. |
expiresInDays / expiresAt | Não | Prazo de validade (GTD). Um ou o outro; omitir assume o prazo padrão da conta. |
Não é uma escolha livre entre os dois. Compra (side: buy) exige quoteAmount
e venda (side: sell) exige amount. Mandar os dois, nenhum, ou o campo do
outro lado é recusado com 400 — uma compra que envia amount recebe a mensagem
Field quoteAmount is required for buy orders.
id é obrigatório e garante idempotência — de forma assíncronaO id é uma chave de idempotência fornecida por você (client order id), e é ele
que vira o orderId da ordem. Um novo POST com o mesmo id para a mesma
conta não cria uma segunda ordem — mas a recusa não vem na resposta: a
requisição repetida também responde 201 com status: OPEN. A duplicata é
identificada em seguida e encerrada em REJECTED
(ver ciclo de vida), com errorMessage: Order already exists,
ficando de pé apenas uma ordem. Ao consultar pelo orderId, o fetchOrder devolve a
primeira ordem criada com esse id, que é a que ficou de pé (ver
como o motivo do encerramento aparece).
Na prática: o reenvio é seguro (não duplica), mas o 201 não confirma que
aquela chamada foi a que sobreviveu. Se a resposta se perder e você reenviar com o
mesmo id, consulte a ordem pelo orderId para saber o desfecho.
Como cancelar uma ordem a limite
- Uma ordem:
cancelLimitOrder(PATCH /orders/limit/orders/{orderId}/cancel). - Em lote:
cancelLimitOrdersBatch(POST /orders/limit/orders/cancel).
Com a ordem em OPEN, o cancelamento registra o pedido e a ordem termina em
CANCELLED (ver ciclo de vida).
A diferença está no estado intermediário, e ela é intencional:
CANCELLING | CANCELLED | |
|---|---|---|
Uma ordem (cancelLimitOrder) | sim, assim que o pedido é aceito | sim, quando o pod conclui |
Em lote (cancelLimitOrdersBatch) | não | sim, um evento por ordem cancelada |
O lote responde "pedido aceito" sem percorrer as ordens do seletor — é o que
permite cancelar um símbolo inteiro, ou a conta inteira, com uma chamada só. Como
ele não percorre, também não marca CANCELLING em cada ordem.
Não espere CANCELLING depois de um cancelamento em lote. O que chega é o
CANCELLED de cada ordem, conforme o pod as processa.
409 não quer dizer que o pedido foi perdidoCancelamento de ordem que não está em OPEN responde 409, e o 409 tem dois
significados diferentes:
- em execução (
TRIGGERED,PROCESSING) — o pedido fica registrado e é honrado automaticamente se a ordem voltar paraOPENpelo re-arm. Se a ordem estiver na mesa da Liqi, o pedido é honrado quando a Liqi a reabre ou quando a revisão seguinte da mesa a encontra, o que pode levar algumas horas; até lá ela seguePROCESSING. Não reenvie: acompanhe a ordem. - já finalizada — o pedido não é registrado, e não há mais o que cancelar.
Reserva de saldo na venda
Uma ordem a limite de venda (side: sell) reserva o saldo do ativo base no
momento da criação, e não só quando dispara. A quantidade reservada é o amount
da ordem (a quantidade da cripto — por exemplo, o BTC em BTC/BRL), nunca
amount × limitPrice.
Na prática, ao criar a venda o saldo daquele ativo sai de free e entra em
used no seu saldo da carteira: ele continua seu, mas fica
bloqueado para aquela ordem enquanto ela está aberta, e por isso não pode ser
usado por outra ordem. O efeito visível no saldo é o mesmo de uma venda a mercado; a
diferença é o momento, que na ordem a limite é a criação e não a execução.
A reserva vale apenas para a venda. Uma ordem a limite de compra (side: buy) não bloqueia saldo na criação: o valor em moeda de cotação (por exemplo,
BRL) permanece livre até a execução.
O que acontece com o saldo reservado depende do desfecho da ordem:
| Desfecho da ordem | Efeito no saldo reservado |
|---|---|
Execução (EXECUTED / CLOSED) | O saldo reservado é consumido — a cripto reservada sai da carteira para liquidar a venda. |
Encerramento sem executar (EXPIRED, CANCELLED, REJECTED) | O saldo é devolvido: volta de used para free e fica disponível de novo. |
Saldo insuficiente na criação
Se, na criação de uma venda, não houver saldo livre suficiente para reservar o
amount pedido, a ordem não fica aberta: ela termina em REJECTED (por
saldo insuficiente). Como cada venda aberta mantém seu saldo reservado, abrir
várias vendas cujo total ultrapasse o saldo disponível faz as que couberem
reservarem normalmente e a excedente ser recusada com REJECTED.
Ciclo de vida resumido
OPEN ──(preço atingido)──▶ TRIGGERED ──(execução)──▶ EXECUTED ──▶ CLOSED
▲ │
└──────────── re-arm (falha recuperável) ──┘
OPEN ──(prazo vencido, expiresAt < now)──▶ EXPIRED
OPEN ──(cancelamento pedido)──▶ CANCELLING ──▶ CANCELLED
qualquer ponto ──(recusa definitiva)──▶ REJECTED
OPEN,TRIGGERED,PROCESSING,EXECUTED— estados ativos (a ordem ainda está em andamento).CANCELLING— cancelamento em andamento: a rota registrou o pedido e o pod conclui (encerra a observação e gravaCANCELLED). Nesse estado a ordem já não executa mais.CLOSED,EXPIRED,CANCELLED,REJECTED— estados finalizados (a ordem não executa mais).
EXECUTED não é o fimEXECUTED significa que a ordem foi preenchida na exchange, e não que o ciclo
terminou: a liquidação segue em andamento e o campo statusGroup ainda vem como
ACTIVE. O estado final de uma ordem executada é CLOSED. Quem para de
consultar em EXECUTED para antes do desfecho.
Acompanhamento de status
As mudanças de status da ordem a limite acontecem de forma assíncrona (disparo, re-arme, conclusão do cancelamento, expiração), e o acompanhamento é por consulta REST:
GET /orders/fetchOrder— lê do registro e responde o estado atual da ordem. É a consulta a usar para confirmar um desfecho.GET /orders/limit/orders— listagem, eventualmente consistente: serve para varrer e reconciliar, não para confirmar o que acabou de acontecer.GET /orders/limit/orders/{orderId}/attempts— a trilha de tentativas de uma ordem: cada disparo e cada re-arme, na ordem em que aconteceram. É o histórico que ofetchOrdernão mostra.
Para reconciliar, use orderId + status + updatedAt: a mesma ordem pode ser lida
várias vezes, e updatedAt é o que diz qual leitura é a mais recente.
watchOrders passou a cobrir a ordem a limiteO WebSocket publica todas as mudanças de status da ordem a limite: abertura,
disparo, re-arm, CANCELLING, CANCELLED, EXPIRED e REJECTED. Cada evento
carrega a ordem completa, no mesmo formato do fetchOrder — com type: "limit"
e os campos de limite.
Esta seção dizia o contrário até agosto de 2026, quando o canal ainda não cobria
essas transiç ões. Se a sua integração faz polling do fetchOrder para saber de
cancelamento ou expiração, ele deixou de ser necessário.
O canal continua sendo complemento, e não substituto da consulta: a entrega ao vivo é
de melhor esforço, e a fonte do estado é o REST. Para reconciliar, use fetchOrder.
Quando a conexão cai, o que você perdeu pode ser recuperado pelo reenvio
(resendMessages), a partir do último sequence que você processou — veja
Reenvio de mensagens perdidas.
EXPIRED — encerramento por tempo
A ordem venceu (expiresAt < now) sem atingir o alvo. É um encerramento por
tempo, não por erro: o mercado simplesmente não chegou ao limitPrice dentro da
validade. Não há falha de execução envolvida.
REJECTED — recusa definitiva
REJECTED é o encerramento por recusa, e não por tempo. Ele pode acontecer
logo depois da criação ou durante a execução — trate-o como desfecho possível em
qualquer ponto, e não só na criação.
Como a execução escolhe a exchange
Quando o preço atinge o alvo, a Liqi cria uma cotação RFQ e executa a ordem por ela, como uma ordem RFQ — ver Execução por cotação RFQ. A cotação sai pelo melhor preço dentro da faixa de execução: só disputam as exchanges cujo preço final cai na faixa. A execução segue essas exchanges na ordem de preço (ou na prioridade configurada para a sua conta, quando houver). Antes de abrir a ordem, cada exchange confere o preço que vai praticar contra o preço cotado: se ele estiver fora da tolerância de slippage do RFQ, ela recusa sem abrir nada e a ordem segue para a próxima exchange. A primeira que estiver dentro executa.
O que acontece quando nenhuma executa depende do motivo da falha, na tabela abaixo.
O que volta para OPEN e o que termina em REJECTED
| Falha na tentativa de execução | Desfecho |
|---|---|
| Nenhuma exchange com preço dentro da faixa no momento da cotação | Volta para OPEN e aguarda o próximo disparo, sem limite de tentativas. Nenhuma cotação é criada |
| Recusa antes do preenchimento — preço fora da tolerância do preço cotado, falta de liquidez (saldo insuficiente no pool, livro sem profundidade, fill or kill sem preenchimento) ou outra recusa da exchange | Volta para OPEN e segue tentando, sem limite de tentativas, até executar ou o prazo vencer |
Erro genérico da exchange (INTERNAL SERVER ERROR) | Volta para OPEN, até três tentativas; na terceira, a ordem permanece em PROCESSING e vai para a análise da mesa da Liqi — ver Erro genérico da exchange |
| Falha interna antes do envio à exchange | Volta para OPEN |
| Mercado inativo para o par | Volta para OPEN; a tentativa entra na trilha com MARKET_UNAVAILABLE (uma vez enquanto a recusa se repetir) |
| Preenchimento com preço fora da tolerância do preço cotado (a exchange executou e o preço saiu da banda) | REJECTED na primeira vez, e a reserva da venda é devolvida |
Nenhuma exchange habilitada para ordem a limite no par (No exchange available for limit orders on this pair) | REJECTED: é condição de configuração, e não recusa transitória |
E, fora do fluxo de execução:
| Quando | Caso |
|---|---|
| Logo após a criação, sem chegar a executar | id duplicado; venda sem saldo suficiente para reservar; saldo do profile em estado inválido |
| Na entrada do fluxo de execução | Ordem sem a quantidade correspondente ao lado; cliente (profile) com compra ou venda desabilitada |
A lista completa de mensagens está em Referência de erros.
Erro genérico da exchange: três tentativas
Quando a exchange responde com um erro genérico (INTERNAL SERVER ERROR), a Liqi
não consegue afirmar duas coisas ao mesmo tempo: nem que o erro é definitivo, nem que
a ordem não chegou a ser aberta do outro lado.
Esse desconhecimento é o que define o tratamento. A ordem a limite não pode ser encerrada por um erro isolado — uma instabilidade momentânea da exchange não deve custar a ordem do cliente. Mas re-armar indefinidamente depois de um desfecho desconhecido tem o risco oposto: executar a mesma ordem mais de uma vez.
O acordo entre os dois é um teto:
- a ordem é tentada até três vezes (a original mais duas);
- entre uma tentativa e outra ela volta para
OPEN, com oexpiresAtoriginal preservado — o prazo não é reiniciado; - se o erro genérico se repetir nas três, a ordem não termina em
REJECTED: ela permanece emPROCESSINGe vai para a mesa da Liqi, que a analisa.
Se a ordem tiver de fato executado na corretora, a Liqi a conclui como executada; se
não, a Liqi a reabre e ela volta para OPEN com o expiresAt original preservado. Se
você cancelar a ordem ou se o prazo vencer, o desfecho é CANCELLED ou EXPIRED. Na
mesa, o cancelamento não é imediato: o 409 registra o pedido (cancelPending: true)
e a ordem é cancelada na próxima revisão da mesa, que pode levar algumas horas, ou
quando a Liqi a reabre. A Liqi não encerra a ordem por esse motivo e o expiresAt
nunca é estendido.
Na prática, um erro realmente transitório se resolve dentro das três tentativas. Um erro permanente que apenas se apresenta como genérico não encerra a ordem: ela fica na mesa até a Liqi decidir, você cancelar ou o prazo vencer.
Entre uma tentativa e outra a ordem fica em OPEN como qualquer outra, e o
expiresAt continua valendo. Se o prazo vencer nesse intervalo, o desfecho é
EXPIRED; se as três tentativas se esgotarem antes, a ordem vai para a mesa da Liqi
e segue PROCESSING. Vale o que acontecer primeiro.
Como o motivo do encerramento aparece
O motivo de cada mudança de status é registrado para auditoria, e é por ele que o suporte da Liqi investiga um caso. Na API, ele aparece só em parte:
- O
GET /orders/fetchOrder(e o evento dowatchOrders, que traz o mesmo objeto) traz o motivo emerrorMessageem toda ordemREJECTED: recusa da exchange, cliente com o lado desabilitado, preenchimento fora da tolerância do preço cotado, par sem exchange para ordem a limite e também as recusas da própria ordem a limite (Order already exists,Insufficient balance,Balance unavailablee quantidade ausente para o lado). Na ordem disparada antes da execução por cotação, o preenchimento fora da faixa na terceira tentativa trazMargin guard blocked 3 executions. Na expiração e no cancelamento, ele vem vazio. - Se o mesmo
idfoi enviado mais de uma vez, ofetchOrderdevolve a primeira ordem criada com esseid, que é a que permanece válida. - Quando a execução passou por mais de uma exchange, o motivo da recusa de cada uma
aparece no
deviationReasondoevaluatedTickers. - O
GET /orders/limit/orderstrazstatus, e não o motivo. - A trilha (
GET /orders/limit/orders/{orderId}/attempts) traz o evento e o status de cada passo e, na tentativa que falhou, o motivo em código no camporeason(ver Motivo de cada tentativa), e não o texto da falha. - A ordem que voltou para
OPENdepois de uma tentativa que falhou traz o mesmo código emlastRejectionReason.
Na prática: o status é o desfecho garantido; o errorMessage explica a rejeição.
Se ele vier vazio numa ordem REJECTED, acione o suporte com o orderId.
Re-arm — falha recuperável volta para OPEN
A ordem a limite é desenhada para re-armar: quando uma tentativa de execução não se
completa por um motivo recuperável, a ordem volta para OPEN (e não para TRIGGERED),
ficando novamente elegível para ser avaliada e disparada no próximo ciclo. Em casos raros, a
ordem pode ser rejeitada (REJECTED) — os casos estão em
REJECTED — recusa definitiva.
Cada etapa do ciclo é carimbada na trilha da ordem, o que permite auditar o que aconteceu em cada tentativa:
avaliou → disparou → tentou → não executou → re-armou
A trilha é lida pelo
GET /orders/limit/orders/{orderId}/attempts, com o
profileId da ordem. Cada entrada traz o evento, o status da ordem naquele momento e, no
disparo, o preço, a exchange e os preços avaliados. A tentativa que volta para OPEN aparece
como REARMED (ou EVALUATED, quando a margem pós-execução barra o preenchimento); FAILED
indica que a tentativa encerrou a ordem.
Motivo de cada tentativa
Cada tentativa que falhou traz o campo reason, com um destes códigos. O disparo que seguiu
para execução e o cancelamento não trazem reason.
| Código | O que aconteceu | O que acontece com a ordem |
|---|---|---|
PRICE_OUT_OF_BAND | nenhuma exchange tinha preço dentro da tolerância da conta no momento da cotação | volta para OPEN |
BELOW_MINIMUM | o valor da ordem ficou abaixo do mínimo da cotação | volta para OPEN |
EXCHANGE_REFUSED | a exchange recusou antes de executar (preço, variação ou outra recusa) | volta para OPEN |
INSUFFICIENT_LIQUIDITY | a exchange recusou por falta de liquidez | volta para OPEN |
EXECUTION_ERROR | erro interno na execução | volta para OPEN até 3 vezes; na terceira, a ordem segue PROCESSING e vai para a mesa da Liqi |
MARKET_UNAVAILABLE | o mercado do par estava indisponível (sem preço utilizável ou sem conexão ativa) | volta para OPEN |
EXECUTION_BEYOND_TOLERANCE | a execução ficou fora da tolerância cotada | REJECTED |
NO_LIMIT_EXCHANGE | o par não tem exchange disponível para ordem a limite | REJECTED |
MANUAL_REOPEN | a operação da Liqi devolveu a ordem para observação | volta para OPEN |
A mesma recusa repetida em ciclos seguidos, sem outra tentativa no meio, aparece uma vez só na trilha.
Quando a ordem volta para OPEN depois de uma tentativa que falhou, o fetchOrder, o
fetchOrders e o evento do watchOrders trazem o motivo dela em
lastRejectionReason, com os mesmos códigos. O campo não aparece em outros status: na ordem
REJECTED, o motivo continua em errorMessage.
Uma mesma ordem pode passar por vários ciclos de re-arm antes de finalmente
executar, expirar por tempo (EXPIRED) ou, no caso de uma falha irrecuperável,
ser rejeitada (REJECTED).
Faixa de execução e margem pós-execução
A ordem a limite só executa dentro de uma faixa de preço em volta do limitPrice. A
largura da faixa é a tolerância de preço da sua conta, um percentual configurado por
conta (maior que 0 e no máximo 50%; o padrão é 1%). A tolerância vale para o lado em que
o preço fica melhor que o alvo.
| Lado | Faixa em que a ordem pode executar |
|---|---|
Compra (buy) | De limitPrice × (1 − tolerância) até limitPrice |
Venda (sell) | De limitPrice até limitPrice × (1 + tolerância) |
Exemplo: compra com limitPrice 400.000 e tolerância de 1,5% — a ordem só executa com o
preço entre 394.000 e 400.000. Na venda, com o mesmo alvo, entre 400.000 e 406.000.
As duas pontas estão dentro da faixa.
Isso vale dos dois lados:
- Preço pior que o
limitPrice(compra acima, venda abaixo): nunca executa. Não há tolerância nesse sentido: o limite é o preço que você definiu. - Preço melhor que o
limitPrice, mas fora da faixa: também não executa. Uma compra comlimitPrice500.000 quando o mercado está em 350.000 não é executada: a ordem ficaOPENaté o preço entrar na faixa ou o prazo vencer.
A faixa vale no disparo e na cotação: o disparo só acontece com preço dentro dela, a cotação
só escolhe exchange com preço dentro dela e o preço cotado é conferido contra ela antes de a
ordem seguir para a exchange. Cotação fora da faixa não executa: a ordem volta para OPEN.
Na execução, a referência passa a ser o preço cotado, como na ordem RFQ: a exchange
aceita uma variação em volta dele, para os dois lados, dentro da tolerância de slippage do
RFQ da sua conta. Preço fora dessa tolerância antes do preenchimento é recusa, e a ordem volta
para OPEN; preenchimento fora dela encerra a ordem em REJECTED e devolve a reserva da venda.
A ordem disparada antes da entrada da execução por cotação segue a regra anterior: a margem é
conferida de novo depois da execução, o preenchimento fora da faixa volta para OPEN e fica na
trilha como EVALUATED, e na terceira tentativa barrada a ordem encerra em REJECTED.
A tolerância da conta é definida pela Liqi. Para alterá-la, fale com o seu contato comercial.
Execução por cotação RFQ
Quando o preço atinge o alvo, a ordem a limite passa a ser executada como uma ordem RFQ:
- O disparo acontece quando o preço entra na faixa de execução (ver Faixa de execução).
- No disparo, a Liqi cria uma cotação RFQ pelo melhor preço dentro da faixa. O preço cotado é o preço da ordem.
- A ordem segue para a exchange pelo mesmo fluxo da ordem RFQ, com a tolerância de slippage do RFQ em volta do preço cotado, para os dois lados.
- Se a execução for recusada antes do preenchimento, a ordem volta para
OPENe pode disparar de novo, com uma cotação nova. Os casos estão em O que volta paraOPENe o que termina emREJECTED.
Depois da cotação, a ordem a limite é igual a uma ordem RFQ, taxas inclusive. O que muda para a sua integração:
fetchOrder,fetchOrderse o canalwatchOrderspassam a trazer o objetoRFQna ordem a limite executada (executedeclosed), com os mesmos campos da ordem RFQ. A ordem continua comtype: "limit"e com os campos de limite.- Liquide pelo objeto
RFQ, como na ordem RFQ. Osettlementcontinua sendo enviado, com os mesmos valores (ver abaixo). - Cada tentativa da trilha
(
fetchLimitOrderAttempts) traz oquotationIde oquotationPriceda cotação criada naquele disparo. Uma tentativa sem cotação (nenhuma exchange com preço dentro da faixa) não traz os dois campos. triggerPrice,triggerExchangeeevaluatedPricecontinuam descrevendo o disparo e não são o preço executado.
A ordem disparada antes da entrada da execução por cotação termina pelo fluxo anterior, sem o
objeto RFQ, liquidada pelo settlement como descrito abaixo.
Liquidação: o objeto settlement
O settlement é mantido por compatibilidade. Ele traz amount, price e cost, e o saldo é
liquidado pelos mesmos valores.
| Campo | Tipo | Ordem executada por cotação RFQ | Ordem disparada antes da execução por cotação |
|---|---|---|---|
amount | string | Quantidade da cotação (= RFQ.amount), nas casas do ativo (8; USDC/BRL, 2) | Na compra, o valor pedido dividido pelo preço executado, já líquido da taxa cobrada em cripto; na venda, a quantidade pedida |
price | string | Preço cotado (= RFQ.price), 2 casas | Preço executado, 2 casas |
cost | string | Valor da cotação em BRL (= RFQ.quoteAmount), 2 casas | Na compra, o valor pedido; na venda, o valor correspondente no preço executado |
- Todos os campos são string decimal, truncados (nunca arredondados).
- Os campos de topo (
amount,filled,cost,price) mostram o que foi executado na exchange e podem diferir do que foi liquidado. Em ordem a limite, liquide peloRFQ(ou pelosettlement), e não pelos campos de topo. - O objeto vem em
executedeclosed, emfetchOrder,fetchOrderse no canalwatchOrders. EmfetchConciliationOrders, os mesmos valores vêm emsettlementAmount,settlementPriceesettlementValue. - Ordem antiga: a ordem a limite executada antes da entrada do
settlementnão traz o objeto; valem os campos de topo. - Execução parcial (só na ordem disparada antes da execução por cotação): o
settlementliquida 100% do pedido, enquanto o topo segue comfilledStatus: "partial-filled". - Ordem a mercado e RFQ não trazem
settlement.
Exemplo, compra de R$ 10 em BTC/BRL executada por cotação (valores ilustrativos): a cotação saiu a 412.000,00 e o cliente recebe 0,00002427 BTC pelos R$ 10,00.
{
"type": "limit",
"side": "buy",
"symbol": "btc/brl",
"status": "closed",
"filledStatus": "filled",
"limitPrice": "415000.00",
"triggerPrice": "411800.00",
"RFQ": {
"exchange": "cryptocom",
"status": "closed",
"filledStatus": "filled",
"amount": "0.00002427",
"quoteAmount": "10.00",
"cost": "10.00",
"price": "412000.00"
},
"settlement": {
"amount": "0.00002427",
"price": "412000.00",
"cost": "10.00"
}
}
Referência de erros
As respostas de erro das rotas têm o corpo {"message": "<texto>"}. Os textos abaixo
são os da API; onde aparece <...>, o valor depende da requisição ou da conta.
Na criação (POST /orders/limit/orders)
| HTTP | Mensagem | Quando |
|---|---|---|
400 | Request body is required | Corpo ausente |
400 | Request body is not valid JSON | Corpo que não é JSON válido |
400 | Field `id` is required | Sem id |
400 | Field `id` must be at most 128 characters | id acima de 128 caracteres |
400 | Field `profileId` is required | Sem profileId |
400 | Invalid Profile | profileId com caractere fora de letras, números, espaço e hífen |
400 | Field `symbol` is required | Sem symbol |
400 | Field `symbol` must be in the `BASE/QUOTE` format, like `BTC/BRL` | symbol fora do formato |
400 | Field `side` must be `buy` or `sell` | side inválido |
400 | Field `limitPrice` must be a positive number | limitPrice ausente, zero, negativo ou não numérico |
400 | Field `limitPrice` is out of the supported range | limitPrice acima do valor suportado |
400 | Field `timeInForce` supports only `GTD` | timeInForce diferente de GTD |
400 | Send exactly one of `amount` or `quoteAmount` | Os dois campos de quantidade, ou nenhum |
400 | Field `amount` must be a positive number / Field `quoteAmount` must be a positive number | Quantidade zero, negativa ou não numérica |
400 | Field `quoteAmount` is required for `buy` orders | Compra com amount |
400 | Field `amount` is required for `sell` orders | Venda com quoteAmount |
400 | Field `quoteAmount` supports at most 2 decimal places | quoteAmount com mais de 2 casas |
400 | Field `amount` supports at most <casas> decimal places for <symbol> | amount com mais casas que o par aceita |
400 | Field `quoteAmount` is below the minimum of R$<mínimo> for <symbol> | Compra abaixo do mínimo do par |
400 | Order value (amount x limitPrice) R$<valor> is below the minimum of R$<mínimo> for <symbol> | Venda abaixo do mínimo do par |
400 | Send `expiresAt` or `expiresInDays`, not both | Os dois campos de prazo |
400 | Field `expiresInDays` must be an integer greater than zero | expiresInDays inválido |
400 | Field `expiresInDays` cannot exceed <máximo> for this account | Prazo acima do máximo da conta |
400 | Field `expiresAt` must be a unix timestamp in seconds | expiresAt inválido |
400 | Field `expiresAt` must be in the future | expiresAt no passado |
400 | Field `expiresAt` cannot exceed <máximo> days for this account | Prazo acima do máximo da conta |
400 | Field `channel` must be a non-empty string | channel vazio |
400 | Order channel `<channel>` not found for this account | channel não cadastrado na conta |
403 | Limit order is not enabled for this account | Ordem a limite não habilitada na conta |
403 | Profile buy order disabled / Profile sell order disabled | Cliente com o lado da ordem desabilitado |
404 | AccountId not found | Credencial sem conta associada |
500 | Internal Server Error | Falha interna; a ordem não foi criada |
No cancelamento de uma ordem (PATCH /orders/limit/orders/{orderId}/cancel)
| HTTP | Mensagem | Quando |
|---|---|---|
400 | Path parameter `orderId` is required | Sem orderId no caminho |
400 | Invalid JSON body | Corpo que não é JSON válido |
400 | Field `profileId` is required | Sem profileId |
404 | Limit order not found | Ordem inexistente para o profile |
404 | AccountId not found | Credencial sem conta associada |
409 | Limit order is executing — cancel request registered and will be honored if the order returns to OPEN | Ordem em execução: o pedido fica registrado (cancelPending: true) |
409 | Limit order is already finalized — cancel request not registered | Ordem já finalizada: nada a cancelar (cancelPending: false) |
500 | Internal server error | Falha interna |
No cancelamento em lote (POST /orders/limit/orders/cancel)
| HTTP | Mensagem | Quando |
|---|---|---|
400 | Send exactly one of `symbol`, `orderIds` or `profileId` | Nenhum seletor, ou mais de um |
400 | Field `orderIds` must contain non-empty strings | orderIds só com valores vazios |
400 | Invalid JSON body | Corpo que não é JSON válido |
404 | AccountId not found | Credencial sem conta associada |
500 | Internal server error | Falha interna; o pedido não foi registrado |
Depois da criação, de forma assíncrona
Estes desfechos não vêm na resposta da requisição: a ordem muda de status depois.
Acompanhe pelo fetchOrder ou pelo watchOrders.
| Desfecho | Causa | errorMessage |
|---|---|---|
REJECTED | id duplicado na conta | Order already exists (só na duplicata; o fetchOrder devolve a primeira ordem do id) |
REJECTED | Venda sem saldo livre para reservar | Insufficient balance |
REJECTED | Saldo do profile em estado inválido | Balance unavailable |
REJECTED | Ordem sem a quantidade correspondente ao lado | For buy orders, 'quoteAmount' is required. / For sell orders, 'amount' is required. |
REJECTED | Cliente com o lado da ordem desabilitado | Profile buy order disabled / Profile sell order disabled |
REJECTED | Preenchimento com preço fora da tolerância do preço cotado (a exchange executou e o preço saiu da banda), na primeira vez | o texto da recusa da execução — descritivo, não é código estável |
REJECTED | Par sem exchange habilitada para ordem a limite | No exchange available for limit orders on this pair |
REJECTED | Só na ordem disparada antes da execução por cotação: preenchimento fora da faixa de execução na terceira tentativa | Margin guard blocked 3 executions |
OPEN (re-arm) | Nenhuma exchange com preço dentro da faixa no momento da cotação, ou cotação fora da faixa (lastRejectionReason: PRICE_OUT_OF_BAND) | — |
OPEN (re-arm) | Valor da ordem abaixo do mínimo da cotação (BELOW_MINIMUM) | — |
OPEN (re-arm) | Recusa da exchange antes do preenchimento — preço fora da tolerância do preço cotado ou outro motivo (EXCHANGE_REFUSED), sem limite de tentativas | — |
OPEN (re-arm) | Falta de liquidez (INSUFFICIENT_LIQUIDITY), sem limite de tentativas | — |
OPEN (re-arm) | Erro genérico da exchange, antes da terceira tentativa (EXECUTION_ERROR) | — |
OPEN (re-arm) | Falha interna antes do envio à exchange (EXECUTION_ERROR) | — |
OPEN (re-arm) | Mercado inativo ou sem preço utilizável para o par (MARKET_UNAVAILABLE); a tentativa entra na trilha uma vez enquanto a recusa se repetir | — |
OPEN (re-arm) | Só na ordem disparada antes da execução por cotação: preenchimento fora da faixa de execução, antes da terceira tentativa | — |
EXPIRED | Prazo vencido sem atingir o alvo | vazio |
CANCELLED | Cancelamento concluído | vazio |
Resumo
| Status | Terminal? | Significado |
|---|---|---|
OPEN | Não | Registrada e aguardando o preço-alvo (estado para onde o re-arm devolve) |
TRIGGERED | Não | Preço atingido, execução em andamento |
CANCELLING | Não | Cancelamento pedido e em andamento (o pod conclui para CANCELLED) |
EXECUTED | Não | Preenchida na exchange, liquidação em andamento (statusGroup ainda ACTIVE) |
CLOSED | Sim | Encerrada com execução concluída — estado final de uma ordem executada |
EXPIRED | Sim | Prazo vencido (expiresAt < now) sem atingir o alvo |
CANCELLED | Sim | Cancelamento concluído |
REJECTED | Sim | Recusa logo após a criação (venda sem saldo, id duplicado) ou recusa definitiva no fluxo de execução — lista dos casos. Falta de liquidez não cai aqui: re-arma |
A execução é por cotação RFQ criada no disparo: a ordem executada traz o objeto RFQ, e é
por ele que se liquida. Nenhuma exchange dentro da faixa, recusa antes do preenchimento (preço
fora da tolerância da cotação, falta de liquidez), falha interna ou erro genérico (até três
vezes) → re-arm → OPEN (nova tentativa, com cotação nova). Preenchimento fora da tolerância da
cotação, recusa logo após a criação ou cliente com o lado desabilitado → REJECTED. Fim do
prazo → EXPIRED. EXECUTED não é
terminal; o fim é CLOSED. Venda reserva o ativo base na criação (sai de free
para used); saldo devolvido em EXPIRED/CANCELLED/REJECTED e consumido na
execução. O motivo de toda rejeição aparece em errorMessage.