Como diagnosticar uma falha na API REST do WordPress

Uma falha da API REST pode vir de credencial/capacidade, rota ou método incorreto, bloqueio do servidor, plugin ou erro do cliente. Registre a URL do endpoint (sem segredo), método, horário, código HTTP e corpo JSON de erro; compare uma chamada pública e, quando apropriado, a chamada autenticada com usuário autorizado.

Antes de começar

Em Ferramentas → Saúde do site → Status, procure avisos de API REST e loopback. No navegador, abra DevTools → Network, reproduza uma vez e anote a requisição que falha, status, método e resposta. Confira a rota raiz /wp-json/ para saber se o índice responde e confirme a rota/método nos recursos disponíveis. Não copie cookies, cabeçalhos de autorização nem tokens para tickets públicos.

Passo a passo

1. Interprete o resultado antes de alterar configuração: 2xx indica resposta bem-sucedida; 3xx pede conferir destino e canonicalização; 400 normalmente aponta parâmetros/corpo/método inválidos; 401 indica autenticação ausente/inválida; 403 indica permissão insuficiente ou bloqueio; 404 pede verificar caminho, namespace, ID e se o plugin que registra a rota está ativo; 429 indica limite imposto por serviço/host; 5xx requer verificar log PHP/servidor e falha do plugin/tema. São pistas, não prova única da causa: leia também o campo JSON code, message e data.status da resposta WordPress.
2. Se falhar apenas no navegador e não em cliente autorizado, veja a requisição OPTIONS de preflight, Access-Control-Allow-Origin, protocolo/host mistos e console CORS. CORS não é correção de autenticação; não abra a API para qualquer origem como teste em produção.
3. Reproduza em staging. Desative cache e isole conflito com plugin/tema por método seguro (por exemplo, Health Check em modo de diagnóstico); altere uma variável por vez. Para 401/403, confira usuário, Application Password/token, permissões e firewall; para 404, confira discovery/rota; para 5xx, correlacione horário com logs e escale ao host.
4. Repita a mesma requisição após a correção e confirme resposta esperada e função da tela que dependia dela. Registre status, rota, horário e mudança aplicada, sem registrar credenciais.

Limites e cuidados

Não compartilhe tokens, cookies, cabeçalhos de autorização nem dados pessoais. Evite testes destrutivos em endpoints de escrita: use staging e uma conta de menor privilégio.

Continue na biblioteca

Explore manutenção de sites para encontrar orientações relacionadas.

Fontes oficiais: referência da API REST do WordPress, como usar a API REST e Saúde do site.

Conteúdo da biblioteca de Diego Henrich. Confira as fontes citadas e valide orientações que dependem da versão de uma plataforma ou serviço.