GUIA

Erros

Formato de erros, códigos e estratégias de retry da Storefront API.

Formato de Erro

A API retorna erros no formato padrão GraphQL. Cada erro inclui uma message e um code nas extensions:

Códigos de Erro

CódigoHTTPDescrição
UNAUTHENTICATED200Operação requer autenticação. O usuário não está logado ou a sessão expirou.
BAD_REQUEST200Query malformada, sintaxe inválida ou campos obrigatórios ausentes.
UNHANDLED_ERROR200Erro interno do servidor. Contate o suporte se persistir.
STOREFRONT_RATE_LIMIT_EXCEEDED429Limite de tokens da API excedido. Aguarde e tente novamente.
QUERY_COMPLEXITY_EXCEEDED429Query muito complexa (muitos campos). Simplifique ou divida em múltiplas queries.
RATE_LIMIT_EXCEEDED429Limite de rate para mutation específica excedido.

Erros de Rate Limit (429)

Quando o rate limit é excedido, a resposta inclui headers para ajudar no retry:

HeaderDescrição
X-RateLimit-LimitLimite total de tokens na janela.
X-RateLimit-RemainingTokens restantes na janela atual.
X-RateLimit-ResetTimestamp ISO 8601 de quando a janela reseta.
Retry-AfterSegundos até que novas requests sejam aceitas.

Veja o Guia de Rate Limits para detalhes sobre custos de tokens e limites.

Erros de Validação

Erros de validação de input retornam detalhes sobre os campos inválidos na mensagem. Verifique os campos obrigatórios documentados em cada mutation.

Estratégia de Retry

Para erros de rate limit (429), use exponential backoff:

  1. Aguarde o tempo indicado no header Retry-After
  2. Se não houver header, aguarde 1s, depois 2s, 4s, 8s...
  3. Máximo de 5 retries antes de falhar definitivamente
Dica: Erros UNAUTHENTICATED não devem ser retried. Redirecione o usuário para a tela de login. Erros UNHANDLED_ERROR podem ser retried uma vez, mas se persistirem indicam um bug no servidor.

Erro de Autenticação

JSON
{
  "data": null,
  "errors": [{
    "message": "Not authenticated",
    "code": "UNAUTHENTICATED"
  }]
}

Erro de Rate Limit

JSON
{
  "errors": [{
    "message": "Storefront API rate limit exceeded for read operations. Try again in 12 seconds.",
    "extensions": {
      "code": "STOREFRONT_RATE_LIMIT_EXCEEDED",
      "operationType": "read",
      "retryAfterSeconds": 12
    }
  }]
}

Erro de Complexidade

JSON
{
  "errors": [{
    "message": "Query too complex (estimated 45 fields, limit 20).",
    "extensions": {
      "code": "QUERY_COMPLEXITY_EXCEEDED",
      "complexity": 45,
      "limit": 20
    }
  }]
}

Retry com Exponential Backoff

JavaScript
async function fetchWithRetry(query, variables, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('/graphql', {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, variables })
    });

    if (response.status !== 429) {
      return response.json();
    }

    const retryAfter = response.headers.get('Retry-After');
    const waitMs = retryAfter
      ? parseInt(retryAfter) * 1000
      : Math.pow(2, attempt) * 1000;

    await new Promise(r => setTimeout(r, waitMs));
  }
  throw new Error('Max retries exceeded');
}