Limites de uso

Cada plano tem dois limites independentes: uma cota de requisições por período de cobrança e um limite por minuto (burst). O período reinicia a cada renovação da assinatura.

Limites por plano

A cota conta apenas requisições cobradas — veja Cobrança de requisições. Pacotes de requisições e créditos extras concedidos aumentam a cota do período atual; eles expiram quando esse período termina e não passam para a renovação ou para um plano ativado imediatamente. O limite por minuto conta tentativas e não aumenta com créditos extras. Enquanto houver créditos extras, as chamadas cobradas usam esse saldo primeiro; a cota própria do plano começa a ser consumida depois. Tentativas rejeitadas também podem contar para o limite por minuto.

Headers de limite

Depois que a chave e o plano são identificados, a resposta informa o estado das políticas do plano:

RateLimit-Policy: "burst";q=30;w=60, "quota";q=5000;w=2592000
RateLimit: "burst";r=27;t=41, "quota";r=4318;t=1209600
RateLimit-Limit: 30
RateLimit-Remaining: 27
RateLimit-Reset: 41

RateLimit-Limit, -Remaining e -Reset repetem a política burst no formato antigo, para clientes que não interpretam campos estruturados. Algumas respostas de erro não trazem esses headers. Em caso de 429, siga o Retry-After. Se um erro ocorrer antes da verificação da cota, os headers podem mostrar apenas o limite por minuto.

O valor q da política quota já inclui os créditos extras disponíveis no período. A contabilização interna desses créditos não reduz esse teto; somente novas requisições cobradas reduzem r.

Planos com cota ilimitada omitem a política quota. A política burst continua sendo aplicada normalmente. Créditos extras continuam sendo consumidos primeiro; depois que acabam, as chamadas seguem pelo plano ilimitado.

Quando o limite é atingido

Nenhuma das duas consome cota.

Limites de transporte

As rotas públicas atuais aceitam apenas GET, sem corpo. O gateway recusa com 413 payload_too_large qualquer corpo declarado acima de 1 MiB (1.048.576 bytes) e também corpos transmitidos sem um tamanho confiável.

Respostas da transportadora são lidas com limite de 1 MiB depois da descompressão. Uma resposta maior, um redirecionamento inesperado ou uma falha de leitura vira 502 courier_unavailable, não consome cota e nunca é repassada parcialmente. O tempo limite continua valendo até o fim do corpo.

Respeitando os headers

Melhor do que reagir ao 429 é nunca chegar nele:

async function track(code, key) {
  const res = await fetch(`https://api.pacotevicio.dev/v1/track/${code}`, {
    headers: { "X-API-Key": key },
  });

  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return track(code, key);
  }

  // Desacelere antes de bater no limite.
  const remaining = Number(res.headers.get("RateLimit-Remaining") ?? Infinity);
  if (remaining <= 2) {
    const reset = Number(res.headers.get("RateLimit-Reset") ?? 1);
    await new Promise((r) => setTimeout(r, reset * 1000));
  }

  return res;
}

Aumentar seus limites

Acesse Plano e Cobrança no menu do portal.