HTTP 상태 코드

누구인지 모르는 것과, 알지만 자격이 없는 것의 차이입니다.

토큰이 만료된 경우는 401 입니다. 클라이언트가 갱신 후 재시도하면 성공할 수 있기 때문입니다. 일반 사용자가 관리자 API 를 부른 경우는 403 입니다.

정보 노출을 줄이려고 일부러 404 를 쓰는 경우도 있습니다. 남의 자원 id 를 넣었을 때 403 을 주면 "그 자원이 존재한다"는 사실이 새어 나갑니다. 그래서 존재 자체를 숨겨야 하는 자원은 404 로 응답합니다.

흔한 실수: 401 을 "권한 없음"으로 답하는 것. 이름(Unauthorized)이 오해를 부르지만 실제 의미는 인증 실패입니다.

영구인지 임시인지가 다르고, 그 차이가 캐시와 검색 색인에 영향을 줍니다.

301 은 브라우저가 캐시하므로 잘못 걸면 되돌리기 어렵습니다. 사용자가 캐시를 지울 때까지 옛 주소로 접근할 수 없습니다. 그래서 확실할 때만 씁니다.

메서드 보존 차이도 있습니다. 301 과 302 는 POST 를 GET 으로 바꾸는 구현이 있어, 그것을 막아야 하면 308 이나 307 을 씁니다.

흔한 실수: 페이지를 잠시 점검할 때 301 을 쓰는 것. 캐시되어 복구 후에도 사용자가 못 들어옵니다. 임시면 302 입니다.

클라이언트가 무엇을 해야 하는지를 코드로 알려주는 것이 목적입니다.

여기에 본문으로 기계가 읽는 code, 사람이 읽는 message, 어느 필드가 틀렸는지, request_id 를 함께 담습니다.

흔한 실수: 모든 오류를 200 이나 500 으로 뭉뚱그리는 것. 200 은 성공과 실패를 구분할 수 없게 만들고, 500 은 클라이언트의 무한 재시도와 잘못된 장애 알림을 유발합니다.

사용자 영향을 먼저 끊고, 원인은 그 다음에 찾습니다.

3번을 2번 뒤에 두는 이유는 롤백이 가장 빠른 완화라서입니다. 원인을 다 알기 전에 되돌려도 됩니다.

그리고 5xx 는 클라이언트에게 "재시도해도 된다"는 뜻이므로 재시도가 몰려옵니다. 백오프와 차단기가 없으면 복구 중에 다시 밀립니다.

흔한 실수: 4xx 로 응답해야 할 것을 5xx 로 보내 놓고 장애로 대응하는 것. 알림이 하루 수천 건 울리면 아무도 보지 않게 되므로, 코드 분류를 먼저 바로잡아야 합니다.