Limites de requisição

Como a Sellit trata volume de requisições, o que fazer ao receber 429 e boas práticas para uma integração saudável.

Política de uso

A API da Sellit opera sob uso justo (fair use): o volume normal de uma integração de ERP ou marketplace cabe folgado nos limites. Rajadas muito acima do padrão podem ser desaceleradas para proteger a estabilidade da plataforma e das demais lojas.

O orçamento é contado por credencial — a combinação de loja e aplicativo. Duas lojas atendidas pelo seu sistema têm orçamentos separados, e um aplicativo não consome o da mesma loja em outro.
Para sincronizações grandes, prefira lotes (ex.: PATCH /variants com várias combinações) a muitas chamadas unitárias.
Espace as chamadas em vez de dispará-las todas de uma vez; distribua no tempo quando possível.

Os números

O quê	Limite
Qualquer chamada em `/api/v1`	120 por minuto
`POST /api/v1/uploads`	60 por minuto e 5.000 por dia

O envio do arquivo em si (o PUT na uploadUrl) não passa por esta API e não consome nada — só o pedido da URL conta. Uma migração de catálogo inteira cabe nos 5.000 diários; acima disso, fale com o suporte antes de começar.

As chamadas recusadas por escopo insuficiente (403) também consomem orçamento. Um laço repetindo a mesma chamada com o escopo errado leva a 429: corrija os escopos do token em vez de tentar de novo.

Precisa de um volume acima do comum (migração, catálogo enorme, sincronização frequente)? Fale com o suporte para alinharmos a janela ideal antes de escalar.

Resposta 429 (Too Many Requests)

Se você exceder o ritmo tolerado, a API responde 429. Quando houver um tempo de espera sugerido, ele vem no header Retry-After (em segundos). Trate o 429 como transitório: espere e tente de novo.

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{ "error": "Muitas requisições. Aguarde e tente novamente." }

Backoff exponencial (recomendado)

Respeite o Retry-After quando presente; caso contrário, use backoff exponencial com um teto de tentativas. O mesmo vale para erros 5xx.

javascript

async function callWithRetry(fn, { maxRetries = 5 } = {}) {
  let attempt = 0
  while (true) {
    const res = await fn()
    if (res.status !== 429 && res.status < 500) return res
    if (attempt >= maxRetries) return res

    const retryAfter = Number(res.headers.get("retry-after"))
    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : Math.min(30000, 2 ** attempt * 1000) // 1s, 2s, 4s, 8s...
    await new Promise((r) => setTimeout(r, waitMs))
    attempt++
  }
}

Boas práticas

Sincronize deltas, não a base inteira: para pedidos use dateType=updated com from/to (veja Recursos).
Prefira webhooks a polling sempre que possível.
Envie um User-Agent identificando seu sistema e versão (ex.: MeuERP/1.0) — ajuda no diagnóstico se algo desacelerar.