Sửa lỗi WordPress REST API 404: Cách khắc phục 'rest_no_route'

TL;DR: Khắc phục nhanh trong 60 giây

Trong khoảng 90% trường hợp, lỗi này xảy ra do các quy tắc ghi lại (rewrite rules) của WordPress không đồng bộ hoặc đường dẫn tĩnh (permalinks) của bạn vẫn đang ở chế độ 'Plain'.

• Đăng nhập vào Dashboard WordPress.
• Đi tới Cài đặt > Đường dẫn tĩnh.
• Chọn Tiêu đề bài viết (hoặc bất kỳ tùy chọn nào khác ngoài 'Plain').
• Nhấn Lưu thay đổi.

Hành động đơn giản này sẽ làm mới (flush) các quy tắc ghi lại của bạn. Hãy tải lại endpoint API; nó thường sẽ hoạt động ngay lập tức.

Tại sao điều này xảy ra?

Khi bạn yêu cầu một tài nguyên như /wp-json/wp/v2/posts và nhận được phản hồi rest_no_route, điều đó có nghĩa là máy chủ vẫn hoạt động, nhưng WordPress bị mất phương hướng. Nó không thể khớp URL của bạn với một hàm cụ thể.

{
    "code": "rest_no_route",
    "message": "Không tìm thấy route nào khớp với URL và phương thức yêu cầu",
    "data": {
        "status": 404
    }
}

Lỗi này thường bắt nguồn từ một trong ba nút thắt cổ chai sau:

• Vô hiệu hóa Pretty Permalinks: REST API dựa vào slug /wp-json/, slug này không tồn tại trong cài đặt 'Plain'.
• Định tuyến máy chủ Web: Nginx hoặc Apache không chuyển tiếp yêu cầu đến index.php một cách chính xác.
• Sai lệch phương thức: Bạn đang cố gắng POST dữ liệu đến một endpoint chỉ chấp nhận yêu cầu GET.

Cách sửa 1: Cấu hình cấp máy chủ

Dành cho người dùng Apache

Đảm bảo tệp .htaccess của bạn tồn tại trong thư mục gốc (thường là /var/www/html/). Nó phải chứa khối định tuyến WordPress tiêu chuẩn. Nếu tệp này thiếu hoặc không có quyền ghi, API sẽ bị lỗi.

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

Kiểm tra tệp virtual host của bạn. Nếu AllowOverride được đặt thành None, Apache sẽ bỏ qua hoàn toàn tệp .htaccess. Hãy đổi nó thành AllowOverride All.

Dành cho người dùng Nginx

Nginx không nhận diện .htaccess. Bạn phải chỉ định rõ ràng cách xử lý các yêu cầu không khớp với tệp vật lý. Mở cấu hình trang web của bạn (thường nằm trong /etc/nginx/sites-available/default) và tìm khối location:

location / {
    try_files $uri $uri/ /index.php?$args;
}

Chạy nginx -t để kiểm tra lỗi cú pháp, sau đó khởi động lại dịch vụ bằng systemctl reload nginx.

Cách sửa 2: Gỡ lỗi các Route API tùy chỉnh

Các endpoint mặc định vẫn hoạt động nhưng các endpoint tùy chỉnh lại bị lỗi? Vấn đề có khả năng nằm ở logic register_rest_route của bạn. Một sai lầm phổ biến là quên bao bọc việc đăng ký trong hook rest_api_init.

add_action( 'rest_api_init', function () {
  register_rest_route( 'myplugin/v1', '/data', array(
    'methods' => 'GET',
    'callback' => 'my_awesome_func',
    'permission_callback' => '__return_true',
  ) );
} );

Kiểm tra các phương thức HTTP của bạn. Nếu bạn định nghĩa route là GET nhưng lệnh gọi fetch() trong JavaScript lại gửi POST, WordPress sẽ trả về lỗi 404 rest_no_route. Hãy kiểm tra kỹ xem URL có khớp chính xác với namespace không: yoursite.com/wp-json/myplugin/v1/data.

Xác minh và Kiểm tra

Kiểm tra API base xem nó có phản hồi hay không. Sử dụng terminal để kiểm tra header nhanh:

curl -I https://yourdomain.com/wp-json/

Phản hồi HTTP/1.1 200 OK có nghĩa là API vẫn ổn định. Nếu bạn thấy một loạt JSON lộn xộn, hãy sử dụng JSON Formatter để kiểm tra. Điều này thường tiết lộ các thông báo (notice) hoặc cảnh báo (warning) PHP ẩn đang làm hỏng cấu trúc JSON và gây lỗi cho ứng dụng frontend của bạn.

Các lỗi thường gặp cần lưu ý

• Plugin bảo mật: Các công cụ như 'All In One WP Security' hoặc 'Hide My WP' thường vô hiệu hóa REST API đối với người dùng chưa đăng nhập. Hãy kiểm tra cài đặt 'WP REST API' của các plugin này.
• Cloudflare Firewall: Nếu bạn chỉ thấy lỗi 403 hoặc 404 trên môi trường production, WAF của Cloudflare có thể đang gắn cờ các lệnh gọi API của bạn là đáng ngờ.
• Dấu gạch chéo cuối (Trailing Slashes): Một số thiết lập máy chủ rất khắt khe. Nếu /wp-json/my-endpoint/ thất bại, hãy thử /wp-json/my-endpoint (không có dấu gạch chéo).
• ModSecurity: Trên hosting dùng chung (shared hosting), ModSecurity có thể chặn các yêu cầu wp-json. Hãy kiểm tra 'Error Logs' trong bảng điều khiển hosting nếu vấn đề vẫn tiếp diễn.