Cota e cache

Cada chave tem 60 requisições por minuto; passado isso, a API responde 429 com quanto esperar. Guarde as recomendações em cache por contexto e não gaste a cota duas vezes na mesma coisa.

Como se conta

Conta-se por chave, depois de autenticar. Uma requisição sem chave não gasta a cota de ninguém.
O orçamento se reabastece aos poucos, não por janela fixa.
Passado o orçamento, a resposta é 429 rate_limited com Retry-After em segundos.

// Se você chama a API direto, o status e o header bastam.
if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After") ?? 1); // segundos
  // não tente antes; e procure o loop que o causou
}

// Um 429 diz quanto esperar.
if resp.StatusCode == http.StatusTooManyRequests {
    wait, _ := strconv.Atoi(resp.Header.Get("Retry-After")) // segundos
    _ = wait // sem recomendação por agora; a página segue
}

O que fazer com um 429

Esperar o que diz Retry-After, não menos.
Não tentar de novo em loop. O SDK não repete sozinho uma requisição de recomendações: tryGetRecommendations devolve null e a página segue. Os sinais, sim, são reenviados, com espera crescente.
Procurar o loop. Quase sempre é um render que se repete: um efeito sem dependências, um observer que dispara várias vezes, uma requisição por card.

O que guardar em cache

Uma recomendação vale enquanto dura a visualização. Guardá-la economiza cota, e o comprador vê a mesma lista ao voltar.

O quê	Chave de cache	Por quanto tempo
Uma recomendação de página de produto	`surface + placement_key + context_item_id`	A sessão da página; alguns minutos no máximo
Uma recomendação de carrinho	`surface + placement_key + hash(cart_items)`	Até o carrinho mudar
Um produto do catálogo	`item_id`	Minutos: o preço e o estoque mudam

Não guarde uma resposta vazia porque o motor não respondeu: ele pode voltar em segundos. Nem uma recomendação além da sessão: decision_id (o id da recomendação) amarra os sinais, e uma recomendação velha atribui errado.

O que você vai ver

Um 429 traz Retry-After e um request_id. Com isso e a aba Rede você acha a requisição que se repete.

Se você não vê

O que acontece	O que fazer
`429` em produção com tráfego normal	Uma requisição por card gasta N por página. Peça uma só recomendação para a listagem
`429` em testes de carga	É o esperado: use várias chaves ou o ambiente local
Não vem `Retry-After`	Um proxy o removeu. Espere um segundo

Chaves e segurança

Por que a cota faz parte da segurança da chave.

Erros

Cada erro da API, com o código e o que fazer.

​Como se conta

​O que fazer com um 429

​O que guardar em cache

​O que você vai ver

​Se você não vê