Limites

Os limites protegem a loja: nenhuma integração pode deixar o checkout lento para quem está comprando.

Por token: o balde

Cada integração, e cada acesso pelo login do CLI, tem um balde de chamadas: cabem 40 chamadas seguidas, e ele se enche 4 por segundo (o padrão; ver a carga inicial, abaixo). Uma sincronização que chama aos poucos nunca bate no limite; a que dispara em laço passa a esperar.

Toda resposta diz como está o balde:

Cabeçalho	O que diz
`RateLimit-Limit`	Quantas chamadas cabem no balde.
`RateLimit-Remaining`	Quantas ainda cabem agora.
`RateLimit-Reset`	Em quantos segundos o balde fica cheio de novo.

Passou do limite, a resposta é 429 (rate_limited) com o cabeçalho Retry-After, em segundos. Os dois tokens de uma integração dividem o mesmo balde. GET /token diz o tamanho do balde e o ritmo em rate_limit.

A carga inicial: o limite ampliado

Para a carga inicial do catálogo de um ERP, ou para a integração grande que sincroniza o tempo todo, a Denaryx amplia o limite das integrações da loja. Fale com o suporte da Denaryx antes de começar.

Faixa	Chamadas seguidas	Por segundo	Validade
Padrão	40	4	Sem prazo.
Ampliado	100	10	Sem prazo, ou até 90 dias.
Carga inicial	200	20	Até 14 dias; depois, volta sozinha ao padrão.

A faixa nova vale na próxima chamada. Leia o limite pelos cabeçalhos RateLimit-* ou por GET /token: em rate_limit, expires_at diz quando o limite ampliado volta ao padrão (null sem prazo). O acesso pelo login do CLI fica sempre no padrão.

Por endereço: tokens inválidos

Um endereço que manda 20 tokens inválidos em 10 minutos passa a receber 429 (too_many_invalid_tokens) até o fim da janela, mesmo com um token bom. Confira o token com uma chamada a GET /token antes de pôr a integração para rodar.

A API ocupada

A API atende um número limitado de chamadas da API Admin ao mesmo tempo, e cada consulta ao banco tem prazo de 10 segundos. Cada integração tem no máximo 3 chamadas em andamento ao mesmo tempo, mesmo com o limite ampliado. Acima disso, a resposta é 503 (busy ou timeout) com Retry-After. Chame de novo depois da espera; se o timeout se repetir, peça menos itens por vez. Na carga inicial, até 3 chamadas em paralelo aproveitam o limite ampliado inteiro.

Boas práticas

Respeite o Retry-After e, nos erros 5xx, espere cada vez mais entre as tentativas.
Prefira as rotas em lote e os filtros por data de atualização a ler tudo de novo.
Mande as escritas com Idempotency-Key: repetir depois de um erro de rede fica seguro. Ver Idempotência.