Uma integração de produção nunca deve assumir que toda chamada de API retorna sucesso. Veja os erros mais comuns e como tratá-los.

404 — Perfil não encontrado ou privado

Não é uma falha do sistema, é um resultado esperado. Trate como "sem dado disponível", não como exceção crítica.

429 — Limite de requisições excedido

Pare de tentar imediatamente, espere o tempo indicado no header de resposta, e retente com backoff (ver idempotência e retries).

401 — Token inválido ou expirado

Verifique se o token está corretamente configurado nas variáveis de ambiente — esse erro costuma ser de configuração, não de uso da API.

502/503 — Instabilidade temporária

Erros de infraestrutura do lado do provedor (não do dado em si). A prática correta é uma nova tentativa automática após um pequeno intervalo, sem descontar da sua cota.

Padrão recomendado de tratamento

try:
    resp = requests.get(url, headers=headers, timeout=10)
    resp.raise_for_status()
    return resp.json()
except requests.HTTPError as e:
    codigo = e.response.status_code
    if codigo == 404:
        return None
    elif codigo == 429:
        aguardar_e_retentar()
    else:
        logar_erro(codigo)
        raise