وقتی ویرایشگر بلوکی ذخیره نمی‌کند، Site Health از REST API ایراد می‌گیرد یا یک integration پاسخ نامعتبر می‌گیرد، «REST API خراب است» هنوز تشخیص کافی نیست. پاسخ 401 و 403 بیشتر به احراز هویت یا policy مربوط‌اند، 404 به route و rewrite، و 500 به اجرای PHP. ابتدا status، URL، method و body واقعی را ثبت کنید.
پاسخ سریع: endpoint پایه /wp-json/ را آزمایش کنید، پاسخ JSON و headerها را ببینید، سپس همان route را با method و هویت واقعی تکرار کنید. خاموش کردن کامل WAF، عمومی کردن endpoint خصوصی یا غیرفعال کردن verification TLS راه‌حل امن نیست.
علائم را به یک درخواست دقیق تبدیل کنید
- URL و namespace، مانند
wp/v2یاwc/v3 - method شامل GET، POST یا PUT
- status و response body
- ناشناس یا کاربر واردشده بودن درخواست
- زمان، IP و request ID
باز شدن endpoint پایه فقط نشان می‌دهد REST dispatcher در دسترس است؛ مجوز و منطق route خاص را تضمین نمی‌کند.
401 و 403: هویت یا مجوز
nonce منقضی، cookie دامنه اشتباه، Application Password نامعتبر، capability ناکافی یا rule امنیتی می‌تواند درخواست را رد کند. تفاوت پیام خود وردپرس با صفحه HTML تولیدشده توسط CDN/WAF مهم است. credential و nonce را در log عمومی نگذارید. ساعت سیستم و HTTPS نیز در جریان‌های امضاشده بررسی شوند.
404 و rest_no_route
permalink را از پنل یک بار ذخیره نکنید مگر اینکه اثر تغییر rewrite را می‌دانید. ابتدا بررسی کنید route واقعاً توسط افزونه ثبت شده، method مجاز است و درخواست به وردپرس می‌رسد. در Nginx، front controller باید مسیرهای لازم را به index.php برساند؛ کپی rule ناشناخته ممکن است فایل‌های استاتیک یا امنیت را خراب کند.
500 و پاسخ غیر JSON
HTML خطای PHP، صفحه proxy یا warning قبل از JSON می‌تواند client را با «invalid JSON» متوقف کند. content type و ابتدای پاسخ را ببینید و timestamp را با PHP-FPM و debug.log وردپرس تطبیق دهید. stack trace را از نخستین کد پروژه دنبال کنید.
روش تشخیص مرحله‌ای
- در پنجره Network درخواست خراب را با حفظ log ثبت کنید.
- endpoint پایه و route هدف را جدا آزمایش کنید.
- درخواست ناشناس و authenticated را اشتباه مقایسه نکنید.
- CDN، reverse proxy و origin را با header و request ID دنبال کنید.
- افزونه امنیتی یا cache را فقط در staging و هدفمند آزمایش کنید.
- پس از اصلاح، read و write و خطاهای مجوز را smoke test کنید.
wp rewrite list
wp plugin list --status=activeاین فرمان‌ها اطلاعات می‌خوانند؛ خروجی را با root درست سایت اجرا و اطلاعات حساس را حذف کنید.
Cache و proxy
پاسخ‌های authenticated یا دارای nonce نباید مانند محتوای عمومی cache شوند. تغییر host یا scheme در proxy می‌تواند cookie و redirect را خراب کند. اگر حلقه ورود دارید، راهنمای Redirect Loop را ببینید. purge بدون اصلاح policy فقط موقت است.
خطا را در مرورگر چگونه بخوانیم؟
در DevTools به تب Network بروید، درخواست ناموفق را انتخاب کنید و بخش‌های Headers، Payload و Response را جدا ببینید. یک status بدون متن پاسخ معمولاً کافی نیست. برای نمونه، پاسخ 403 با header مربوط به CDN با پاسخ JSON وردپرس که کد rest_forbidden دارد، دو مسیر بررسی متفاوت می‌خواهد. گزینه Preserve log کمک می‌کند درخواست پیش از redirect از فهرست حذف نشود.
اگر لازم است نمونه درخواست را برای تیم فنی بفرستید، ابتدا cookie، nonce، Authorization، ایمیل و داده مشتری را حذف کنید. قابلیت Copy as cURL مفید است، اما خروجی آن اغلب credential دارد و نباید بدون پاک‌سازی در تیکت یا پیام عمومی قرار گیرد.
تفکیک مشکل هسته، افزونه و زیرساخت
خطا فقط روی یک endpoint اختصاصی معمولاً به افزونه ثبت‌کننده route یا مجوزهای آن نزدیک‌تر است. خرابی همه مسیرهای /wp-json/ بیشتر rewrite، proxy، WAF یا اجرای PHP را مطرح می‌کند. اگر فقط عملیات نوشتن ناموفق است ولی GET کار می‌کند، method، nonce، capability، محدودیت اندازه body و ruleهای امنیتی را بررسی کنید.
در سایت چندزبانه یا multisite نیز URL واقعی درخواست را با site و domain فعال مقایسه کنید. پاسخ سالم از دامنه دیگر الزاماً مشکل دامنه فعلی را رد نمی‌کند؛ cookie و تنظیمات شبکه ممکن است برای هر دامنه متفاوت باشند.
آزمون با WP-CLI و curl چه محدودیتی دارد؟
curl برای دیدن status، header و TLS مفید است، اما درخواست مرورگر واردشده را بدون cookie و nonce بازسازی نمی‌کند. WP-CLI نیز کد وردپرس را از محیط خط فرمان اجرا می‌کند و الزاماً از CDN و reverse proxy عبور نمی‌کند. بنابراین موفقیت WP-CLI در کنار شکست مرورگر می‌تواند نشانه‌ای از ایراد لایه HTTP باشد، نه اثبات سالم بودن کل مسیر.
curl -i https://example.com/wp-json/
wp rest route listدامنه نمونه را با دامنه خود جایگزین کنید. در محیطی که فرمان دوم پشتیبانی نمی‌شود، آن را نصب یا حدس نزنید؛ فهرست فرمان‌های WP-CLI همان پروژه را بررسی کنید. برای endpoint خصوصی، credential را مستقیماً در history پوسته ننویسید.
پس از اصلاح چه چیزهایی را تست کنیم؟
- بارگذاری و ذخیره یک نوشته آزمایشی در ویرایشگر
- درخواست خواندن عمومی بدون افشای داده خصوصی
- درخواست نوشتن با کاربر مجاز و رد شدن کاربر غیرمجاز
- عملکرد webhook یا integration وابسته
- نبود پاسخ cacheشده بین دو کاربر
- ثبت نشدن خطای تازه در PHP و proxy log
اشتباه‌های رایج
- غیرفعال کردن REST API برای پنهان کردن هشدار Site Health
- ارسال credential داخل URL یا screenshot
- اعتماد به status 200 وقتی body صفحه خطا است
- تغییر هم‌زمان permalink، WAF و افزونه‌ها
- تست GET به‌جای POST خراب
چه زمانی کمک تخصصی لازم است؟
اگر خطا فقط پشت CDN، برای webhook یا هنگام نوشتن داده رخ می‌دهد، trace چند لایه لازم است. سرویس رفع مشکل فنی وردپرس می‌تواند درخواست را از مرورگر تا PHP و route دنبال کند.
پرسش‌های متداول
آیا REST API خطر امنیتی است؟
خود API بخشی از وردپرس است؛ routeها باید permission callback و احراز هویت درست داشته باشند. خاموش کردن کامل جای کنترل دسترسی را نمی‌گیرد.
چرا wp-json باز است ولی ویرایشگر ذخیره نمی‌کند؟
ذخیره به route، method، nonce و capability خاص نیاز دارد. endpoint پایه آزمون کامل نیست.
چرا پاسخ JSON با HTML شروع می‌شود؟
warning PHP، صفحه WAF یا redirect ورود ممکن است قبل از payload آمده باشد؛ header و log همان درخواست را ببینید.