워드프레스 REST API 오류가 나요

REST API 오류라는 설명만으로 원인을 정할 수 없습니다. 브라우저 개발자 도구, 사이트 건강, 외부 연동 프로그램 중 어디에서 오류를 확인했는지 먼저 기록합니다.

변경 없이 확인할 항목

1. 요청 URL, HTTP 메서드, 발생 시각을 기록합니다.
2. 응답의 HTTP 상태와 Content-Type을 확인합니다.
3. JSON 응답이면 code, message, data.status를 기록합니다.
4. HTML 오류 화면이면 화면 문구와 응답을 보낸 서버·프록시 정보를 확인합니다.
5. 관리자 화면 안의 요청인지, 외부 프로그램에서 보낸 요청인지 구분합니다.

WordPress REST API는 JSON을 요청·응답 형식으로 사용하고 오류도 HTTP 상태와 JSON으로 반환합니다. 응답이 HTML이면 WordPress REST API의 JSON 오류로 단정하지 말고 웹서버, 보안 장비 또는 호스팅 오류 화면인지 확인해야 합니다.

/wp-json/이 404로 응답할 때

WordPress REST API 색인은 기본적으로 /wp-json/에서 확인할 수 있습니다. 고유주소를 사용하지 않는 환경에서는 같은 색인을 /?rest_route=/로 요청합니다.

비교가 끝나기 전에 .htaccess나 Nginx 규칙을 덮어쓰지 않습니다. 현재 규칙과 되돌리는 방법을 먼저 기록해야 합니다.

인증 요청이 거부될 때

관리자 화면 안에서 실행하는 REST API 요청은 WordPress 로그인 쿠키와 wp_rest nonce를 사용합니다. 수동 Ajax 요청이라면 _wpnonce 매개변수나 X-WP-Nonce 헤더가 필요합니다. nonce가 없으면 로그인 쿠키가 있어도 현재 사용자를 인증되지 않은 사용자로 처리합니다.

외부 프로그램은 관리자 화면의 쿠키 인증을 그대로 사용할 수 없습니다. WordPress는 HTTPS에서 Application Password를 사용하는 방법을 제공하며, 요청 사용자는 해당 작업에 필요한 권한도 갖고 있어야 합니다.

인증 헤더를 보냈지만 서버에서 받지 못했다면 CGI 환경이나 웹서버가 Authorization 헤더를 제거하는지 확인합니다. 비밀번호, Application Password, 쿠키, nonce와 Authorization 값은 로그나 문의 내용에 넣지 않습니다.

JSON 응답에 rest_cookie_invalid_nonce, Cookie check failed, HTTP 403이 함께 표시되면 Cookie check failed에서 쿠키 인증 nonce 분기를 확인합니다.

REST API 전체를 끄지 마세요

WordPress 공식 FAQ는 REST API 전체를 비활성화하면 REST API에 의존하는 관리자 기능이 깨질 수 있다고 안내합니다. 공개 접근을 제한해야 한다면 어떤 Route와 사용자가 대상인지 먼저 정하고, 인증 실패의 JSON 코드와 HTTP 상태를 기록한 뒤 플러그인·테마·보안 설정의 공식 문서를 확인합니다.

담당자에게 전달할 내용

WordPress 버전:오류 확인 위치:요청 URL·메서드·발생 시각:HTTP 상태·Content-Type:JSON code·message·data.status:/wp-json/ 확인 결과:/?rest_route=/ 확인 결과:관리자 내부 요청 또는 외부 연동:사용한 인증 방식(비밀값 제외):최근 고유주소·웹서버·보안 설정 변경: