Desativação da credencial

Os bloqueios de limite e de uso indevido expiram sozinhos. Já a credencial que mantém taxa alta de 429 por dias seguidos é desativada, e essa desativação só termina quando você a religa.

A regra

Todo dia, às 10h00 (horário de Brasília), medimos o dia anterior inteiro de cada credencial que recebeu ao menos um 429. Usamos o dia fechado porque o dia corrente mudaria de resultado a cada medição.

O limiar

A credencial passa da régua quando as duas condições acontecem no mesmo dia:

Só a proporção puniria quem faz poucas chamadas (3 recusas em 50 dão 6%). Só a quantidade puniria integrações grandes e saudáveis. Juntas, descrevem volume alto de chamadas que não trouxeram dado.

Todas as causas de 429 contam igual, inclusive a de requisição idêntica.

A escada

Um único dia dentro da régua zera a contagem, automaticamente. Dia sem nenhuma chamada também zera. A contagem é de dias de calendário seguidos: dias acima da régua intercalados por um dia bom não desativam nada.

Quem recebe e-mail

Toda credencial que teve ao menos um 429 no dia recebe um e-mail no endereço do responsável pela conta. Dentro da régua, é um relatório informativo; acima dela, é um aviso da escada. Credencial já inativa ou apagada não recebe e-mail e não entra na escada.

O escopo: só a credencial

A régua vale igual em produção e sandbox, e cada credencial tem sua própria contagem.

O que você vê quando ela é desativada

Todas as rotas passam a responder:

HTTP/1.1 401 Unauthorized

{
  "message": "Invalid or expired access token",
  "status": 401
}

A mensagem engana: o token não expirou nem é inválido, a credencial foi desligada. Reemitir token não resolve. Se a emissão de token funciona mas toda chamada da API responde 401, a credencial está desativada.

Como reativar

Ajuste a frequência das chamadas e religue a credencial no painel do Developers. Não há prazo de espera nem chamado. O clientSecret não muda: não é preciso gerar credencial nova.

Reincidência

Credencial já desativada por esta regra uma vez perde a carência: se voltar a passar da régua, é desativada no primeiro dia, sem os avisos. Sem isso, a régua viraria um ciclo de desativar e religar sem corrigir a integração.

Como não chegar aqui

• Troque consulta repetida por webhook. É a única mudança que elimina o problema: você passa a ser avisado.
• Sem webhook, use GET /v1/orders/polling a cada 30 segundos. Ele devolve só o que mudou e fica fora da regra de uso indevido.
• Trate o Retry-After. Quem espera o tempo indicado quase não acumula 429.
• Não reenvie antes da resposta. A recusa por requisição idêntica some com um await.
• Não busque o detalhe do pedido a cada evento. É o erro mais comum e a chamada mais cara da API.

Veja Como tratar o 429 para distinguir as causas e Uso indevido para a regra de repetição.