# Fluxo de diagnóstico

1. A resposta é `401`? **Pare.** O token está ausente, expirado, revogado ou fora do cabeçalho. Confira o cabeçalho; se persistir, peça um token novo a um admin.
2. É `403`? **Pare.** Falta escopo (`projects:write`, `deploy`, `env:write`, `env:reveal`, `domains:write`, `volumes:write`, `databases:write`, `logs:read`, `templates:deploy`, `assets:*`). Peça um token com o escopo da rota ([Tokens e escopos](/seguranca/tokens-e-escopos/)).
3. É `404`? O recurso não existe **ou não é do seu time**: os dois casos são indistinguíveis. Confira o id/nome que você usou (listando com `GET`) e **não** tente adivinhar ids.
4. É `429` ou `503` (`unavailable`, `authz_unavailable`, `unavailable`)? **Repita** com espera ([Rate limit e retry](/erros/rate-limit-e-retry/)).
5. É `409`? `name_taken` / `slug_taken`: outro nome ou slug. `project_quota_exceeded`: pare e peça aumento. `deploy_in_progress`: acompanhe o deploy em andamento. `nothing_to_rollback`, `backup_not_ready`: o destino ainda não terminou com sucesso; espere. Outros `409`: leia o estado do recurso antes de agir. (`idempotency_conflict` é `422` nas rotas de plataforma: gere chave nova.)
6. É `400`, `413`, `415`? Corrija o dado e envie de novo; não repita igual. Consulte a [tabela de erros](/erros/tabela/).
7. É `422`? Arquivos (`malware_detected`, `svg_unsafe`, `archive_*`): não reenvie o mesmo arquivo; SVG, veja [como reexportar](/cdn/classes-de-arquivo-e-varredura/#por-que-meu-svg-foi-recusado-e-como-reexportar); malware, avise uma pessoa. Banco: `quota_exceeded` ⇒ pare de escrever e peça aumento.
8. Upload `202 pending`? Não reenvie: consulte o arquivo com backoff até `scan.status` mudar ([Uploads pending](/cdn/galerias/#uploads-pending-202-como-esperar)).
9. `422 unresolved_reference`, `reference_cycle`, `invalid_reference`, `reference_too_deep` ou `value_too_large` ao disparar o deploy? Nada foi criado: `details.references` lista os nomes; corrija as variáveis e dispare de novo. Deploy terminou em `failed`? Leia o log de build e o de runtime (`error.code` e `error.message` do deployment dizem a causa). Com `error.code = image_requires_root`, declare `build.user` (uid[:gid], nunca root) ou troque a imagem. Um `429` ao disparar deploy pode ser o limite `deploys_per_hour`: espere o `Retry-After`. Depois dispare novo deploy.
10. Deploy em `blocked`? Outro serviço do grupo falhou: corrija o que falhou primeiro.
11. URL da CDN respondendo `451`? O arquivo foi retirado por segurança. Não insista; avise uma pessoa.