Pular para o conteúdo principal

Ordem a Limite — status finais e retry

Disponibilidade

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:

CampoObrigatório?O que é
idSimChave de idempotência do cliente (client order id). Ver detalhe abaixo.
profileIdSimCliente (profile) dono da ordem.
symbolSimPar de negociação — ex.: BTC/BRL, ETH/BRL, USDC/BRL.
sideSimbuy (compra) ou sell (venda).
limitPriceSimPreç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 amountSimTamanho 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 / expiresAtNãoPrazo de validade (GTD). Um ou o outro; omitir assume o prazo padrão da conta.
O campo de quantidade depende do lado da ordem

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íncrona

O 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​

Com a ordem em OPEN, o cancelamento registra o pedido e a ordem termina em CANCELLED (ver ciclo de vida).

As duas rotas avisam de formas diferentes

A diferença está no estado intermediário, e ela é intencional:

CANCELLINGCANCELLED
Uma ordem (cancelLimitOrder)sim, assim que o pedido é aceitosim, quando o pod conclui
Em lote (cancelLimitOrdersBatch)nãosim, 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.

Ordem em execução: o 409 não quer dizer que o pedido foi perdido

Cancelamento 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 para OPEN pelo 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 segue PROCESSING. 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.

Compra não reserva

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 ordemEfeito 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 grava CANCELLED). 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 fim

EXECUTED 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 o fetchOrder nã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.

O canal watchOrders passou a cobrir a ordem a limite

O 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çãoDesfecho
Nenhuma exchange com preço dentro da faixa no momento da cotaçãoVolta 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 exchangeVolta 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 à exchangeVolta para OPEN
Mercado inativo para o parVolta 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:

QuandoCaso
Logo após a criação, sem chegar a executarid duplicado; venda sem saldo suficiente para reservar; saldo do profile em estado inválido
Na entrada do fluxo de execuçãoOrdem 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 o expiresAt original 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 em PROCESSING e 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 do watchOrders, que traz o mesmo objeto) traz o motivo em errorMessage em toda ordem REJECTED: 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 unavailable e quantidade ausente para o lado). Na ordem disparada antes da execução por cotação, o preenchimento fora da faixa na terceira tentativa traz Margin guard blocked 3 executions. Na expiração e no cancelamento, ele vem vazio.
  • Se o mesmo id foi enviado mais de uma vez, o fetchOrder devolve a primeira ordem criada com esse id, 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 deviationReason do evaluatedTickers.
  • O GET /orders/limit/orders traz status, 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 campo reason (ver Motivo de cada tentativa), e não o texto da falha.
  • A ordem que voltou para OPEN depois de uma tentativa que falhou traz o mesmo código em lastRejectionReason.

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ódigoO que aconteceuO que acontece com a ordem
PRICE_OUT_OF_BANDnenhuma exchange tinha preço dentro da tolerância da conta no momento da cotaçãovolta para OPEN
BELOW_MINIMUMo valor da ordem ficou abaixo do mínimo da cotaçãovolta para OPEN
EXCHANGE_REFUSEDa exchange recusou antes de executar (preço, variação ou outra recusa)volta para OPEN
INSUFFICIENT_LIQUIDITYa exchange recusou por falta de liquidezvolta para OPEN
EXECUTION_ERRORerro interno na execuçãovolta para OPEN até 3 vezes; na terceira, a ordem segue PROCESSING e vai para a mesa da Liqi
MARKET_UNAVAILABLEo mercado do par estava indisponível (sem preço utilizável ou sem conexão ativa)volta para OPEN
EXECUTION_BEYOND_TOLERANCEa execução ficou fora da tolerância cotadaREJECTED
NO_LIMIT_EXCHANGEo par não tem exchange disponível para ordem a limiteREJECTED
MANUAL_REOPENa operação da Liqi devolveu a ordem para observaçãovolta 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.

LadoFaixa 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 com limitPrice 500.000 quando o mercado está em 350.000 não é executada: a ordem fica OPEN até 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:

  1. O disparo acontece quando o preço entra na faixa de execução (ver Faixa de execução).
  2. 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.
  3. 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.
  4. Se a execução for recusada antes do preenchimento, a ordem volta para OPEN e pode disparar de novo, com uma cotação nova. Os casos estão em O que volta para OPEN e o que termina em REJECTED.

Depois da cotação, a ordem a limite é igual a uma ordem RFQ, taxas inclusive. O que muda para a sua integração:

  • fetchOrder, fetchOrders e o canal watchOrders passam a trazer o objeto RFQ na ordem a limite executada (executed e closed), com os mesmos campos da ordem RFQ. A ordem continua com type: "limit" e com os campos de limite.
  • Liquide pelo objeto RFQ, como na ordem RFQ. O settlement continua sendo enviado, com os mesmos valores (ver abaixo).
  • Cada tentativa da trilha (fetchLimitOrderAttempts) traz o quotationId e o quotationPrice da 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, triggerExchange e evaluatedPrice continuam 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.

CampoTipoOrdem executada por cotação RFQOrdem disparada antes da execução por cotação
amountstringQuantidade 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
pricestringPreço cotado (= RFQ.price), 2 casasPreço executado, 2 casas
coststringValor da cotação em BRL (= RFQ.quoteAmount), 2 casasNa 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 pelo RFQ (ou pelo settlement), e não pelos campos de topo.
  • O objeto vem em executed e closed, em fetchOrder, fetchOrders e no canal watchOrders. Em fetchConciliationOrders, os mesmos valores vêm em settlementAmount, settlementPrice e settlementValue.
  • Ordem antiga: a ordem a limite executada antes da entrada do settlement não traz o objeto; valem os campos de topo.
  • Execução parcial (só na ordem disparada antes da execução por cotação): o settlement liquida 100% do pedido, enquanto o topo segue com filledStatus: "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)​

HTTPMensagemQuando
400Request body is requiredCorpo ausente
400Request body is not valid JSONCorpo que não é JSON válido
400Field `id` is requiredSem id
400Field `id` must be at most 128 charactersid acima de 128 caracteres
400Field `profileId` is requiredSem profileId
400Invalid ProfileprofileId com caractere fora de letras, números, espaço e hífen
400Field `symbol` is requiredSem symbol
400Field `symbol` must be in the `BASE/QUOTE` format, like `BTC/BRL` symbol fora do formato
400Field `side` must be `buy` or `sell` side inválido
400Field `limitPrice` must be a positive numberlimitPrice ausente, zero, negativo ou não numérico
400Field `limitPrice` is out of the supported rangelimitPrice acima do valor suportado
400Field `timeInForce` supports only `GTD` timeInForce diferente de GTD
400Send exactly one of `amount` or `quoteAmount` Os dois campos de quantidade, ou nenhum
400Field `amount` must be a positive number / Field `quoteAmount` must be a positive numberQuantidade zero, negativa ou não numérica
400Field `quoteAmount` is required for `buy` ordersCompra com amount
400Field `amount` is required for `sell` ordersVenda com quoteAmount
400Field `quoteAmount` supports at most 2 decimal placesquoteAmount com mais de 2 casas
400Field `amount` supports at most <casas> decimal places for <symbol>amount com mais casas que o par aceita
400Field `quoteAmount` is below the minimum of R$<mínimo> for <symbol>Compra abaixo do mínimo do par
400Order value (amount x limitPrice) R$<valor> is below the minimum of R$<mínimo> for <symbol>Venda abaixo do mínimo do par
400Send `expiresAt` or `expiresInDays`, not bothOs dois campos de prazo
400Field `expiresInDays` must be an integer greater than zeroexpiresInDays inválido
400Field `expiresInDays` cannot exceed <máximo> for this accountPrazo acima do máximo da conta
400Field `expiresAt` must be a unix timestamp in secondsexpiresAt inválido
400Field `expiresAt` must be in the futureexpiresAt no passado
400Field `expiresAt` cannot exceed <máximo> days for this accountPrazo acima do máximo da conta
400Field `channel` must be a non-empty stringchannel vazio
400Order channel `<channel>` not found for this accountchannel não cadastrado na conta
403Limit order is not enabled for this accountOrdem a limite não habilitada na conta
403Profile buy order disabled / Profile sell order disabledCliente com o lado da ordem desabilitado
404AccountId not foundCredencial sem conta associada
500Internal Server ErrorFalha interna; a ordem não foi criada

No cancelamento de uma ordem (PATCH /orders/limit/orders/{orderId}/cancel)​

HTTPMensagemQuando
400Path parameter `orderId` is requiredSem orderId no caminho
400Invalid JSON bodyCorpo que não é JSON válido
400Field `profileId` is requiredSem profileId
404Limit order not foundOrdem inexistente para o profile
404AccountId not foundCredencial sem conta associada
409Limit order is executing — cancel request registered and will be honored if the order returns to OPENOrdem em execução: o pedido fica registrado (cancelPending: true)
409Limit order is already finalized — cancel request not registeredOrdem já finalizada: nada a cancelar (cancelPending: false)
500Internal server errorFalha interna

No cancelamento em lote (POST /orders/limit/orders/cancel)​

HTTPMensagemQuando
400Send exactly one of `symbol`, `orderIds` or `profileId` Nenhum seletor, ou mais de um
400Field `orderIds` must contain non-empty stringsorderIds só com valores vazios
400Invalid JSON bodyCorpo que não é JSON válido
404AccountId not foundCredencial sem conta associada
500Internal server errorFalha 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.

DesfechoCausaerrorMessage
REJECTEDid duplicado na contaOrder already exists (só na duplicata; o fetchOrder devolve a primeira ordem do id)
REJECTEDVenda sem saldo livre para reservarInsufficient balance
REJECTEDSaldo do profile em estado inválidoBalance unavailable
REJECTEDOrdem sem a quantidade correspondente ao ladoFor buy orders, 'quoteAmount' is required. / For sell orders, 'amount' is required.
REJECTEDCliente com o lado da ordem desabilitadoProfile buy order disabled / Profile sell order disabled
REJECTEDPreenchimento com preço fora da tolerância do preço cotado (a exchange executou e o preço saiu da banda), na primeira vezo texto da recusa da execução — descritivo, não é código estável
REJECTEDPar sem exchange habilitada para ordem a limiteNo exchange available for limit orders on this pair
REJECTEDSó na ordem disparada antes da execução por cotação: preenchimento fora da faixa de execução na terceira tentativaMargin 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—
EXPIREDPrazo vencido sem atingir o alvovazio
CANCELLEDCancelamento concluídovazio

Resumo​

StatusTerminal?Significado
OPENNãoRegistrada e aguardando o preço-alvo (estado para onde o re-arm devolve)
TRIGGEREDNãoPreço atingido, execução em andamento
CANCELLINGNãoCancelamento pedido e em andamento (o pod conclui para CANCELLED)
EXECUTEDNãoPreenchida na exchange, liquidação em andamento (statusGroup ainda ACTIVE)
CLOSEDSimEncerrada com execução concluída — estado final de uma ordem executada
EXPIREDSimPrazo vencido (expiresAt < now) sem atingir o alvo
CANCELLEDSimCancelamento concluído
REJECTEDSimRecusa 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
dica

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.