API REST do WordPress retornando 404

O que este erro significa e como reconhecê-lo

• Abrir /wp-json/ retorna uma página HTTP 404 em vez do JSON do índice da API REST.
• Um aplicativo JavaScript, aplicativo móvel, cliente REST, editor ou integração informa 404 Not Found para uma solicitação à API do WordPress.
• O front-end do WordPress carrega normalmente enquanto as solicitações REST falham.
• ?rest_route=/ funciona mesmo quando o caminho amigável /wp-json/ retorna 404.
• O índice da API carrega, mas um plugin ou endpoint personalizado retorna 404.
• O WordPress Site Health informa que a API REST está indisponível; o corpo da resposta e o código de status ainda precisam ser verificados para identificar a origem.

Causas principais, por probabilidade

1. Regras de rewrite de links permanentes desatualizadas ou ausentes. Isso é comum após uma migração, alteração de links permanentes, mudança de servidor ou implantação incompleta.
2. O servidor web ou proxy não encaminha /wp-json/ para o WordPress. O suporte a rewrite do Apache, o roteamento try_files do Nginx, o mapeamento do document-root ou as configurações do virtual host podem estar incorretos.
3. Uma regra de segurança, firewall, CDN, cache ou hospedagem está retornando 404. Alguns controles ocultam solicitações bloqueadas retornando não encontrado em vez de proibido.
4. Um plugin ou tema altera o comportamento da API REST. Ele pode remover rotas, restringir o acesso ou filtrar respostas REST.
5. Apenas um endpoint personalizado ou de plugin está incorreto. A solicitação pode ter o namespace, a rota, a versão, o método HTTP ou o ID do recurso incorreto, ou a rota pode não estar registrada.
6. A solicitação aponta para o caminho de instalação ou site incorreto. Alterações de domínio, instalações em subdiretórios, redirecionamentos, configurações desatualizadas do aplicativo e respostas armazenadas em cache podem fazer os clientes usarem um caminho base de API desatualizado.

Como corrigir

1. Confirme o escopo e a origem do 404

Registre o caminho exato da solicitação, o status HTTP, o corpo da resposta, os cabeçalhos da resposta, o método da solicitação e o horário. Verifique se a resposta parece vir do WordPress, do servidor web, de um proxy reverso, de uma CDN ou de uma camada de segurança. Não inclua tokens de acesso, cookies, senhas ou dados privados da resposta nos registros de diagnóstico.

Teste o índice da API REST em /wp-json/ usando um cliente apropriado. Se o índice retornar JSON, mas um endpoint retornar 404, vá diretamente para a etapa 5. Se o próprio índice retornar 404, continue.

2. Atualize as regras de rewrite do WordPress

No painel do WordPress, abra Configurações → Links permanentes e clique em Salvar alterações sem mudar a estrutura de links permanentes selecionada. Isso atualiza a configuração de rewrite do WordPress.

Teste /wp-json/ novamente. Se a automação de implantação ou um painel de controle de hospedagem gerenciar a configuração do servidor, confirme que as configurações de rewrite são persistidas e não substituídas pela próxima implantação.

3. Compare o caminho amigável com a rota de fallback

Teste a API REST usando o fallback de parâmetro de consulta do WordPress: ?rest_route=/ anexado ao endereço inicial normal do site. Use o esquema, o hostname e o caminho de instalação reais. Uma instalação em subdiretório pode exigir que esse caminho continue fazendo parte da solicitação.

• O fallback funciona, mas /wp-json/ falha: o WordPress consegue processar solicitações REST; portanto, investigue os rewrites de URLs amigáveis, as configurações do virtual host, o roteamento do proxy, o mapeamento do document-root e as alterações da migração.
• Ambos falham: verifique os controles de segurança, o roteamento do front controller do servidor, o comportamento do WordPress e dos plugins e o caminho configurado do site ou da instalação.
• Ambas as solicitações ao índice funcionam, mas uma rota personalizada falha: diagnostique especificamente esse endpoint na etapa 5.

4. Verifique o roteamento do servidor web, do proxy e da segurança

No Apache, peça a um administrador autorizado que verifique se o suporte a rewrite está habilitado para o diretório do WordPress e se as regras de rewrite do site estão presentes e são permitidas pela configuração do virtual host. No Nginx ou em um proxy reverso, verifique se as solicitações chegam ao front controller do WordPress e se /wp-json/ não está sendo tratado como um arquivo estático ausente.

Analise os registros relevantes nesta ordem:

1. Logs de acesso e de erro do servidor web para a solicitação com falha.
2. Regras e entradas de cache da CDN, do balanceador de carga e do proxy reverso.
3. Plugins de segurança, firewall, proteção de login e controle REST do WordPress.
4. Regras do WAF no nível da hospedagem que possam classificar o caminho, o método ou os cabeçalhos da solicitação como bloqueados.

Faça uma alteração controlada por vez, registre a configuração original e limpe apenas o cache relevante após a autorização. Não desative amplamente um firewall de produção ou plugin de segurança sem um plano de manutenção aprovado. Se uma regra de segurança for responsável, permita estritamente o caminho e os métodos REST necessários, em vez de contornar toda a proteção.

5. Diagnostique um endpoint específico ausente

Confirme o namespace exato do endpoint, a rota, o segmento de versão, o método HTTP, o caminho final e o identificador do recurso. Compare a solicitação com a documentação da rota ou com o código de registro fornecido pelo plugin ou aplicativo.

Verifique se:

• O plugin ou tema responsável está ativo no ambiente que está sendo testado.
• O registro da rota é executado durante a inicialização REST.
• A rota tem o callback de permissão esperado e não é omitida condicionalmente para a solicitação atual.
• O cliente usa o caminho base da API do site atual, e não um domínio, subdiretório ou configuração de aplicativo armazenada em cache e desatualizada.
• O recurso solicitado realmente existe. Uma publicação, usuário, produto ou outro recurso ausente pode produzir um 404 legítimo no nível do endpoint mesmo quando a API REST está saudável.

Verifique o índice da API ou a resposta de descoberta de rotas, quando disponível. Se a rota esperada estiver ausente, investigue o registro, o status do plugin, o namespace e a configuração específica do ambiente, em vez de tratar o problema como uma indisponibilidade geral da API REST.

6. Verifique novamente após cada alteração controlada

Teste novamente usando um navegador, um cliente de API autorizado e, quando relevante, o aplicativo que informou o erro. Compare o código de status, os cabeçalhos da resposta, o corpo da resposta e a origem da resposta antes e depois de cada alteração. Reverta as alterações temporárias de diagnóstico e documente a configuração final de rewrite, firewall, cache, proxy ou plugin.

Prevenção e como verificar a correção

• Adicione um teste de funcionamento da API REST para /wp-json/ e para cada rota personalizada essencial ao negócio às verificações de migração e implantação.
• Mantenha consistentes entre os ambientes a URL do site WordPress, a URL inicial, o document root e a configuração de subdiretório.
• Gerencie a configuração de rewrite, as regras de proxy, as políticas de firewall e o comportamento do cache como configurações documentadas de implantação, e não como alterações de servidor não documentadas.
• Analise as alterações em plugins de segurança e WAF quanto aos efeitos sobre solicitações REST autenticadas e não autenticadas.
• Monitore o status e a origem da resposta para chamadas de API importantes, para distinguir um 404 gerado por proxy de um 404 gerado pelo WordPress.
• Documente namespaces personalizados, rotas, métodos aceitos, comportamento das permissões e o plugin ou tema responsável por cada endpoint.