Runbook — Debug de API e logs
Use este runbook quando uma API retornar erro, resposta vazia, timeout, problema de CORS ou divergência de dados.
Fluxo recomendado
- Abrir
tools/api-debug-terminal.html. - Testar o endpoint em modo direto.
- Se o navegador bloquear CORS, marcar Usar proxy PHP.
- Conferir status HTTP, headers, body e tempo de resposta.
- Abrir a aba Log servidor para ver os últimos testes.
- Copiar o
cURLgerado para reproduzir o erro fora do navegador. - Depois da manutenção, limpar
logs/api-debug.loge desativar o debug se necessário.
Interpretação rápida
| Código | Significado comum | Ação |
|---|---|---|
| 200 | Requisição OK | Conferir se o JSON veio completo |
| 400 | Parâmetro inválido | Revisar query/body |
| 401 | Sem autenticação | Conferir token/Authorization |
| 403 | Sem permissão | Conferir perfil, IP, CORS ou config |
| 404 | Endpoint errado | Conferir rota e base URL |
| 500 | Erro interno | Conferir log PHP/servidor |
| 504 | Timeout/gateway | Reduzir carga, paginação ou filtros |
Segurança
Nunca deixar api-debug-proxy.php liberado para qualquer domínio. O arquivo api-debug-config.php precisa manter allowed_hosts restrito.