Limites e boas práticas

A plataforma protege a loja contra excesso de chamadas e contra tentativas de adivinhar senhas. Esta página reúne as práticas que fazem uma integração se comportar bem: repetir só o que é seguro, não duplicar pedidos, não consultar à toa.

Se vier um 429

A plataforma usa uma resposta padrão para o excesso de chamadas. Se ela chegar, é assim:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"error":"rate limit exceeded","detail":"too many requests, please try again later"}

Espere o tempo do Retry-After (ou use espera crescente, veja adiante) antes de tentar de novo. O limite é por endereço IP de origem: várias integrações que saem do mesmo endereço (a mesma rede, o mesmo NAT, o mesmo servidor) dividem o mesmo balde.

Bloqueio de conta no login

Errar a senha várias vezes na rota auth_tokens pode bloquear aquele login por um tempo, mesmo com outra senha certa; a rota continua respondendo 401 invalid credentials. A quantidade de tentativas e o tempo de bloqueio são configurações da loja. Por isso, nunca faça login a cada requisição.

Repetir chamadas com segurança

Uma chamada pode falhar sem que você saiba se a plataforma chegou a executá-la (a rede caiu depois do envio, o tempo acabou). Repetir às cegas pode duplicar um pedido. A regra:

Criações não são idempotentes

Idempotente quer dizer que repetir a mesma chamada não muda o resultado além da primeira vez. A API legada não oferece isso: POST /api/v1.0/orders, POST /api/v1.0/users e as demais criações gravam um registro novo a cada chamada.

Por isso, adote este procedimento:

• Guarde o order_id (ou user_id) assim que a resposta 201 chegar.
• Se uma criação deu timeout, consulte antes de repetir: procure o cliente pelo e-mail, procure o pedido pelo número da sua origem ou pelo cliente e pela data. Só crie de novo se ele não existir.
• Registre no seu sistema a ligação entre o seu número de pedido e o order_id da loja.

Espera crescente

Para 429, 503 e 5xx, repita com espera crescente e aleatória (backoff exponencial com jitter): 1 s, 2 s, 4 s, 8 s, cada uma com uma variação aleatória, até um teto de tentativas (por exemplo 5). Respeite o Retry-After quando vier. Para falhas de rede, a mesma estratégia.

import random, time, requests

def get_with_retry(url, auth, tries=5):
    for attempt in range(tries):
        r = requests.get(url, auth=auth, timeout=30)
        if r.status_code not in (429, 503) and r.status_code < 500:
            return r
        wait = float(r.headers.get("Retry-After", 2 ** attempt)) + random.random()
        time.sleep(wait)
    return r

Tempo limite

Defina sempre um tempo limite no seu cliente (30 segundos é um bom começo para leituras e escritas simples; operações em lote pedem mais). Algumas rotas têm um teto no servidor e respondem 503; trate como erro repetível.

Consultar menos

• Varreduras incrementais. Para importar pedidos, guarde a data do último processado e use time_from; descarte duplicados pelo order_id. Não releia o histórico inteiro a cada ciclo.
• Páginas grandes. Use items_per_page=100 em vez de várias páginas pequenas.
• Cache de cadastros. Formas de pagamento, formas de envio e o cadastro de status mudam raramente: leia uma vez e renove de vez em quando.
• Reutilize o token. Um token da rota auth_tokens serve para muitas chamadas; a chave de API com Basic não precisa de login.

Segurança

• Guarde a chave de API, o token e o token de app no servidor. Nunca em código de navegador, em app instalado no aparelho do cliente, em repositório ou em log.
• Crie um usuário só para a integração, com os privilégios mínimos. Quando alguém sai da equipe, a senha dele não derruba a integração.
• Troque as credenciais com uma rotina: a chave pode ser regerada (a anterior deixa de valer na hora), a senha trocada, o token de app revogado.
• Use https sempre.
• Remova credenciais e dados pessoais dos logs. Registre o X-Request-Id, que não é sensível.

Erros comuns

• Fazer login a cada requisição e arriscar o bloqueio da conta.
• Repetir um POST de criação sem conferir se o registro já existe.
• Retentar 400 em loop.
• Esquecer o tempo limite e deixar o processo preso.
• Reler a lista inteira a cada ciclo em vez de buscar só o que mudou.

Veja também