상태 코드

요청을 보낸 쪽은 결과를 알아야 다음 행동을 정합니다. 성공이면 화면을 갱신하고, 로그인이 끊겼으면 로그인 화면으로 보내고, 서버가 잠깐 넘어진 것이라면 조금 뒤 다시 보내야 합니다. 이 판단을 응답 본문의 글자로 하려면 받는 쪽이 문장을 뒤져야 합니다.

페이지덱의 첫 API 가 그랬습니다. 모든 응답을 성공으로 내려보내고 본문 안에 결과를 적어 두는 방식이었습니다. 앱은 본문을 열어 결과 값을 확인해야 했고, 문구가 한 번 바뀌자 오류 화면이 뜨지 않게 됐습니다. 더 큰 문제는 오류율 지표가 0으로 나왔다는 것입니다. 모든 응답이 성공으로 기록되고 있었으니 모니터링 화면은 장애가 난 30분 동안에도 평온했습니다.

그래서 결과를 본문과 별개의 자리에 숫자로 적어 두기로 약속한 것이 이 값입니다. 프로그램이 본문을 열지 않고도 판단할 수 있고, 중간에 있는 장비들도 같은 숫자를 읽습니다.

세 자리 숫자이고 첫 자리가 무리를 가릅니다. 받는 쪽은 대개 첫 자리로 큰 갈래를 정하고 세 자리로 세부 처리를 고릅니다.

• 1xx 는 아직 진행 중이라는 뜻이고 실무에서 직접 다룰 일은 드뭅니다.
• 2xx 는 성공입니다.
• 3xx 는 다른 주소로 가야 한다는 안내입니다.
• 4xx 는 요청한 쪽에 문제가 있다는 뜻입니다. 어떤 HTTP 메서드로 불렀든 같은 규칙으로 읽습니다.
• 5xx 는 받은 쪽, 곧 서버에 문제가 있다는 뜻입니다.

자주 쓰는 값은 열 개 안쪽입니다.

1. 200 은 처리됐고 결과가 본문에 있다는 뜻입니다.
2. 201 은 새로 만들어졌다는 뜻이고 문서를 생성하는 요청의 응답이 여기 해당합니다.
3. 204 는 처리됐고 돌려줄 내용이 없다는 뜻이라 삭제 요청에 자주 씁니다.
4. 301 과 302 는 주소가 옮겨졌다는 안내이고, 301 은 영구 302 는 한시적입니다.
5. 400 은 요청의 형태가 틀렸다는 뜻입니다. 필수 항목이 빠졌거나 숫자 자리에 글자가 왔을 때입니다.
6. 401 은 누구인지 확인되지 않았다는 뜻이고 403 은 확인은 됐지만 그 일을 할 권한이 없다는 뜻입니다. 로그인하지 않은 사람에게는 401, 로그인한 일반 구성원이 관리자 화면을 열면 403 입니다.
7. 404 는 그 자리에 자원이 없다는 뜻입니다.
8. 409 는 지금 상태와 부딪힌다는 뜻입니다. 이미 있는 이름으로 다시 만들려는 요청이 여기 잡힙니다.
9. 429 는 너무 자주 불렀다는 뜻이고 잠시 뒤 다시 보내라는 안내가 함께 옵니다.
10. 500 은 서버 안에서 예상 못 한 오류가 났다는 뜻이고 503 은 지금은 받을 수 없으니 뒤에 다시 오라는 뜻입니다.

이 숫자가 정하는 것은 받는 쪽의 다음 행동입니다. 401 이면 로그인 화면으로 보내고, 429 와 503 이면 잠시 기다려 다시 보내고, 400 이면 다시 보내도 같으니 무엇이 잘못됐는지 알려 줍니다. 5xx 는 다시 보낼 만하고 4xx 는 요청을 고쳐야 한다는 구분이 재시도 규칙의 바탕입니다.

사람이 읽을 설명은 응답에 실려 오는 본문, 곧 페이로드에 적습니다. 숫자는 기계가 읽는 결론이고 본문은 사람이 읽는 이유라, 둘을 함께 보내야 앱이 분기하고 사용자가 이해합니다.

같은 숫자를 사람과 프로그램과 장비가 나눠 읽습니다. 자주 걸리는 자리가 넷입니다.

1. API 문서입니다. 창구마다 어떤 경우에 어떤 숫자를 돌려주는지 적는 것이 문서의 한 절을 차지합니다. 한 서비스 안에서 어떤 창구는 없는 자원에 404 를 주고 다른 창구는 200 에 빈 목록을 주면, 앱은 창구마다 다른 코드를 써야 합니다.
2. 모니터링과 경보입니다. 5xx 비율이 1퍼센트를 넘으면 당번에게 알림을 보내는 식으로 기준을 세웁니다. 숫자를 제대로 쓰지 않으면 이 경보가 작동하지 않습니다.
3. 화면의 오류 처리입니다. 401 은 조용히 로그인으로 보내고, 403 은 권한이 없다고 알리고, 500 은 잠시 뒤 다시 시도하라고 안내합니다. 세 경우에 같은 문구를 띄우면 사용자는 무엇을 해야 할지 모릅니다.
4. 검색 엔진과 중간 장비입니다. 없어진 페이지에 200 을 주면 검색 엔진은 그 페이지를 계속 목록에 두고, 301 로 안내하면 옛 주소의 평가를 새 주소로 넘깁니다. 캐시 장비도 이 숫자를 보고 저장할지 정합니다.

"여기 401 로 주셔야 합니다. 지금 403 이라 앱이 로그인 화면으로 못 보냅니다."

두 숫자의 뜻이 달라 받는 쪽 처리가 갈린다는 지적입니다.

"오류를 200 에 담아 보내고 있어서 5xx 경보가 안 울립니다."

결과를 숫자로 적지 않아 감시가 작동하지 않는다는 말입니다.

"429 면 잠시 뒤 다시 보내고 400 이면 다시 보내지 말아야 합니다."

재시도 규칙을 숫자 무리로 나눈다는 뜻입니다.

태오가 JSON 응답 규격을 정리할 때 정한 것은 둘이었습니다. 결과는 숫자로 적고 이유는 본문에 적는다, 같은 뜻에는 항상 같은 숫자를 쓴다입니다. 창구 서른 개 중 없는 자원에 200 을 주던 일곱 개를 404 로 바꿨고, 검증 실패를 500 으로 던지던 넷을 400 으로 내렸습니다. 그다음 주 오류율 지표가 처음으로 0이 아닌 값을 보여 줬고, 그 값이 두 달째 그 수준이었다는 것도 그때 알았습니다.

전부 성공으로 내려보내고 본문에 오류를 적는 편이 다루기 쉽다고 여기는 경우가 가장 많습니다. 받는 쪽 코드가 한 갈래로 단순해지니 그렇게 보입니다. 하지만 그 선택은 셋을 함께 잃습니다. 오류율 지표가 0이 되어 경보가 죽고, 중간 캐시 장비가 오류 응답을 정상으로 저장해 다른 사용자에게도 같은 화면이 나가고, 재시도해도 되는 경우와 안 되는 경우를 구분할 근거가 없어집니다. 본문에 적는 것은 이유이고 숫자에 적는 것은 결론입니다.

4xx 는 우리 잘못이 아니라고 읽는 것도 흔합니다. 요청한 쪽에 문제가 있다는 뜻이니 서버 쪽에서 할 일이 없어 보입니다. 실제로 특정 창구에 400 이 몰리는 것은 우리 쪽 신호입니다. 문서가 실제 동작과 다르거나, 어느 항목이 왜 틀렸는지 본문에 적지 않아 같은 실수가 반복되거나, 규칙이 지키기 어려운 형태인 경우입니다. 페이지덱의 한 창구에서 400 비율이 12퍼센트였던 이유는 날짜 형식을 두 가지로 받다가 하나만 받게 바꾼 것을 문서에 적지 않았기 때문입니다.