DOCS
Rate•
InícioPara fornecedores logísticos Limitação de taxa da API GraphQL

Limitação de taxa da API GraphQL

Saiba como Zonos calcula os custos de consulta com base na complexidade.

A Zonos limita a taxa de solicitações à API GraphQL com base na complexidade da consulta, e não na contagem de solicitações. Isso garante um uso justo, ao mesmo tempo que permite solicitar exatamente os dados necessários.

Por que limitar a taxa com base na complexidade? 

As APIs REST tradicionais usam limitação de taxa baseada em solicitação, onde cada solicitação consome os mesmos créditos, independentemente de você buscar um campo ou centenas, e de ler ou modificar dados, apesar da diferença significativa na carga do servidor.

A abordagem baseada na complexidade de consulta do GraphQL resolve isso calculando os custos com base nos dados reais solicitados e nas operações realizadas. Isso oferece mais flexibilidade para solicitar o que você precisa, ao mesmo tempo que fornece carga previsível do servidor.

Limite de taxa 

Zonos usa um sistema baseado em pontos onde cada consulta deduz pontos com base em sua complexidade. Você tem um conjunto de pontos disponíveis que:

  • Recarrega 3.000 pontos por segundo (30.000 pontos a cada 10 segundos)
  • Tem capacidade máxima de 300.000 pontos

Isso permite que você faça rajadas ocasionais de consultas complexas, mantendo um ritmo de solicitação sustentável.

Como o custo da consulta é calculado 

Cada solicitação GraphQL tem um custo calculado antes da execução:

Custos básicos

  • Consulta: 5 pontos
  • Mutação: 10 pontos
  • Objeto: 1 ponto por objeto retornado
  • Campos escalares: 0 pontos (grátis)

Campos escalares como strings, inteiros, IDs e booleanos não aumentam o custo. Você paga apenas pela operação base e pelos objetos devolvidos.

Exemplo: consulta simples

1query {
2 landedCost(id: "123") {
3 id
4 createdBy
5 shipToCountry
6 }
7}

Divisão de custos: 5 (consulta base) + 1 (objeto Landed cost) = 6 pontos

Os campos escalares (id, name, currency) são gratuitos.

Exemplo: Consulta com vários objetos

1{
2 orders(first: 10, filter: { status: COMPLETED }) {
3 edges {
4 cursor
5 node {
6 id
7 }
8 }
9 }
10}

Divisão de custos: 5 (consulta base) + 10 (10 pedidos × 1 ponto cada) = 15 pontos

Exemplo: Mutação

1mutation {
2 landedCostCalculate(input: { ... }) {
3 id
4 }
5}

Divisão de custos: 10 (mutação base) + aproximadamente 50 (objetos retornados) = 60 pontos

Um cálculo típico de Landed cost custa cerca de 60 pontos em complexidade.

Visualizando a complexidade da consulta 

Cada resposta da API inclui um cabeçalho zonos-query-complexity mostrando o custo da sua consulta:

1zonos-query-complexity: 58

Este cabeçalho informa exatamente quantos pontos a consulta consumiu. Use-o para monitorar seu uso de API e otimizar consultas caras.

Lidando com limites de taxa 

Se você exceder seu limite de taxa, receberá uma mensagem de erro. Para lidar com limites de taxa de forma eficaz:

Monitore sua complexidade

Verifique o cabeçalho zonos-query-complexity nas respostas para entender os custos da sua consulta e identificar padrões caros.

Implementar lógica de repetição

Se você atingir os limites de taxa, implemente a espera exponencial e a lógica de nova tentativa. Como o balde é reabastecido em 3.000 pontos por segundo, calcule os tempos de espera apropriados com base na complexidade da sua consulta.

Lote com eficiência

GraphQL permite solicitar múltiplas consultas em uma única solicitação:

1{
2 landedCost(id: "landed_cost_123") {
3 id
4 createdAt
5 }
6 order(orderId: "order_123") {
7 id
8 status
9 createdAt
10 }
11}

Melhores práticas 

Solicite apenas o que você precisa

A complexidade da consulta é proporcional aos dados solicitados. Estruture suas consultas para buscar apenas os campos e objetos que você realmente usará.

1query {
2 order(orderId: "order_123") {
3 id
4 status
5 createdAt
6 updatedAt
7 items {
8 id
9 name
10 quantity
11 amount
12 }
13 shipments {
14 id
15 }
16 }
17}

Paginar grandes conjuntos de dados

Ao solicitar vários objetos, use tamanhos de página razoáveis:

1{
2 orders(first: 100, filter: { status: COMPLETED }) {
3 edges {
4 cursor
5 node {
6 id
7 }
8 }
9 }
10}

Solicite de 10 a 50 itens por vez e pagine os resultados conforme necessário, em vez de solicitar centenas de objetos em uma única consulta.

Evite aninhamentos desnecessários

Cada objeto aninhado aumenta sua complexidade. Solicite dados aninhados apenas quando realmente precisar deles.

Esta página foi útil?

Obter suporte·Documentos legais·© 2026 Zonos
Nesta página:
  • Limitação de taxa da API GraphQL
  • Por que limitar a taxa com base na complexidade?
  • Limite de taxa
  • Como o custo da consulta é calculado
  • Visualizando a complexidade da consulta
  • Lidando com limites de taxa
  • Melhores práticas