Desenvolvedores

Erros e limites

Envelope de resposta

Todas as rotas seguem o mesmo envelope. Códigos de erro são estáveis (SCREAMING_SNAKE): trate por error.code; error.message já vem em pt-BR pronta para exibir.

// Sucesso (objeto)
{ "data": { ... } }

// Sucesso (lista paginada por cursor)
{ "data": [ ... ], "pageInfo": { "hasNextPage": true, "endCursor": "opaco" } }

// Erro
{ "error": { "code": "VALIDATION_ERROR", "message": "Mensagem em pt-BR exibível.",
             "details": [{ "field": "email", "issue": "E-mail inválido" }] } }

Paginação por cursor

Listas usam limit (máx. 100) e cursor opaco, sem offset:

terminal

# Página 1
curl ".../storefront/search?q=camiseta&limit=24"
# Página seguinte: repita com o endCursor anterior
curl ".../storefront/search?q=camiseta&limit=24&cursor=ENDCURSOR"

Códigos HTTP

Status	Significado
200 / 201	Sucesso.
400	Requisição malformada (validação); veja error.details por campo.
401	Não autenticado (ex.: CUSTOMER_UNAUTHENTICATED); renove a sessão e repita.
403	Sem permissão, ou loja suspensa (TENANT_SUSPENDED).
404	Não encontrado; inclui host desconhecido (TENANT_NOT_FOUND).
409	Conflito de estado (ex.: Idempotency-Key reusada com payload diferente).
422	Regra de negócio (ex.: divergência de preço/estoque no checkout; CAPTCHA_REQUIRED / CAPTCHA_FAILED no login do cliente).
429	Limite de requisições; respeite o header Retry-After.
500	Erro inesperado.

Rate limits

60 req/min por IP no conjunto /storefront/* (produção).
10 req/min por IP nas rotas sensíveis: login, registro, checkout/complete, cupom e cartão-presente.
Desafio progressivo no login do cliente: 5 falhas do mesmo e-mail em 15 min ligam um desafio por 15 min: em subdomínio meweb.com.br vem 422 CAPTCHA_REQUIRED (reenvie com turnstileToken); em domínio próprio, 429 a cada tentativa em menos de 30 s. Detalhes em Autenticação do cliente.
Resposta 429 inclui Retry-After em segundos; não repita antes disso.

Dica: renderize server-side e cacheie leituras de catálogo no seu front (elas mudam pouco); reserve as chamadas por visitante para carrinho/checkout/conta.

Convenções

Dinheiro em centavos (integer): 7990 = R$ 79,90. Formate com Intl.NumberFormat('pt-BR').
Datas em ISO 8601 UTC (2026-07-09T12:00:00.000Z); converta para o fuso do visitante na exibição.
IDs são ULIDs (strings de 26 caracteres); trate como opacos.