Códigos
Os códigos que a API pública devolve, e o que fazer com cada um.
| Status | code | Quando | O que fazer |
|---|---|---|---|
| 400 | VALIDATION_ERROR | janela > 90 dias, from > to, cursor ilegível | corrija o parâmetro |
| 401 | INVALID_API_KEY | sem header, malformado ou chave desconhecida | verifique o header Authorization |
| 401 | API_KEY_REVOKED | a chave foi revogada | gere outra |
| 401 | API_KEY_EXPIRED | a chave passou da validade | gere outra |
| 403 | API_KEY_SCOPE_DENIED | a chave não tem o escopo da rota; hoje toda chave nasce com tracking:read | não deve acontecer nesta versão; fale com o suporte |
| 403 | API_QUOTA_EXCEEDED | a conta atingiu a cota de uso do período | fale com o suporte; esperar não resolve |
| 404 | — | rota inexistente | verifique o caminho e o prefixo /v1 |
| 429 | — | limite por chave excedido | espere o Retry-After |
| 5xx | — | erro interno da API do PassKey | retente com espera crescente; persistindo, acione o suporte |
401 × 403
A diferença é operacional, não cosmética: 401 pede outra credencial, 403 pede outra permissão. Retentar um 403 com a mesma chave nunca vai funcionar.
Quando retentar
- 400, 401, 403, 404 — não. A mesma chamada falha de novo; conserte a requisição.
- 429 — sim, depois do tempo indicado em Retry-After.
- 5xx — sim, com espera crescente (1s, 2s, 4s…) e um teto de tentativas.