• 목록

API 호출 결과가 200으로 돌아왔으니 주문이나 파일 생성도 끝났다고 생각하기 쉽습니다. 그러나 HTTP 요청이 성공했다는 사실과 서비스 안의 전체 업무가 완료되었다는 사실은 확인 범위가 다를 수 있습니다.

특히 시간이 오래 걸리는 작업을 접수한 뒤 나중에 처리하는 구조에서 이 차이가 중요합니다. 상태 코드를 외우기보다 요청의 목적과 업무 상태를 연결해서 읽는 방법을 정리합니다.

예시에 등장하는 보고서 생성 서비스는 설명을 위해 만든 가상 시스템입니다.

AI 생성 삽화 · 개념 이해를 위한 AI 연출 이미지이며 실제 시스템 구성도나 측정 결과가 아닙니다.

핵심 정리
HTTP 상태 코드는 해당 요청의 결과를 설명합니다. 접수 이후 작업이 남는 API에서는 작업 식별자와 상태 조회를 통해 업무 완료 여부를 별도로 확인해야 합니다.

1. 성공했다고 말하는 대상부터 정합니다

가상의 보고서 서비스에서 사용자가 생성 버튼을 누르면 서버가 작업 목록에 요청을 넣는다고 가정하겠습니다. 이때 접수 성공, 보고서 생성 성공, 결과 파일 다운로드 성공은 서로 다른 사건입니다.

버튼을 누른 직후 모든 단계가 끝난 것처럼 표시하면 사용자는 파일이 없을 때 고장으로 받아들일 수 있습니다. 설계 문서에서는 어떤 요청이 어떤 사건까지 책임지는지 먼저 적습니다.

생성 요청은 접수까지 책임지고 상태 조회 요청은 현재 진행 정보를 반환하는 식으로 나눌 수 있습니다. 이렇게 나누면 요청 자체의 오류와 접수 후 처리 실패를 다른 경로로 보여 줄 수 있습니다.

성공이라는 단어 옆에 대상을 붙이는 작은 습관이 API 해석의 혼동을 줄여 줍니다.

2. 202 응답의 의미를 정확히 읽습니다

HTTP 의미를 정의하는 RFC 9110에서 202 Accepted는 처리 요청을 받아들였으나 처리가 완료되지 않은 상태를 뜻합니다. 나중에 실제 처리가 이루어질지까지 보장하는 응답은 아니며, 응답 내용은 현재 상태와 상태를 확인할 방법을 안내하는 것이 바람직하다고 설명합니다.

따라서 202를 받았다는 이유로 완료 화면을 보여 주는 것은 해당 업무 설계와 맞는지 검토해야 합니다. 반대로 모든 비동기 API가 반드시 같은 응답 본문을 사용한다고 가정할 수도 없습니다.

작업 식별자의 필드명과 조회 주소, 종료 상태의 이름은 서비스 계약을 확인합니다. 상태 코드의 공통 의미를 이해한 뒤 서비스가 정한 추가 약속을 읽는 순서가 필요합니다.

3. 200도 요청한 자원의 의미와 함께 해석합니다

상태 조회 요청이 정상 처리되어 현재 작업 상태를 돌려주는 상황을 생각해 봅니다. 조회 응답은 성공했지만 그 안에 담긴 작업 상태는 실패일 수 있습니다.

예를 들어 가상의 작업 조회 결과가 처리 실패와 사유를 정상적으로 알려 준다면 조회 기능은 제 역할을 한 것입니다. 이때 조회 응답의 성공을 보고 파일 생성까지 성공했다고 기록하면 모니터링 결과가 왜곡됩니다.

어떤 API에서는 업무 오류를 오류 응답으로 표현하고 다른 API에서는 상태 자원 안에 표현할 수 있으므로 계약을 확인해야 합니다. 중요한 것은 숫자 하나에서 전체 업무 결과를 추론하지 않는 것입니다.

요청의 목적이 작업 실행인지 현재 상태 읽기인지 구분하면 응답을 읽는 기준도 명확해집니다.

4. 작업 식별자로 이어지는 상태를 추적합니다

가상의 보고서 요청이 작업 번호 R17을 반환했다고 가정하겠습니다. 이후 화면은 같은 번호를 기준으로 대기, 처리 중, 완료 또는 실패를 확인하도록 설계할 수 있습니다.

상태 이름은 예시이며 실제 API에서 지원하는 값은 별도로 확인합니다. 새로 고침 후에도 같은 작업을 찾을 수 있어야 사용자가 버튼을 반복해서 누르는 일을 줄일 수 있습니다.

완료 상태에서는 결과 파일의 위치와 접근 가능 여부를 확인하고 실패 상태에서는 다음 행동에 필요한 안내를 제공합니다. 처리 중이라는 표시만 무한히 유지되면 사용자는 기다려야 하는지 문의해야 하는지 알 수 없습니다.

오래 걸리는 경우의 안내와 조회를 종료할 기준도 접수 화면을 만들 때 함께 정하는 편이 좋습니다.

5. 응답을 못 받았을 때는 완료 여부가 불확실할 수 있습니다

클라이언트가 기다리다가 연결을 종료했다고 해서 서버가 아무 일도 하지 않았다고 단정할 수는 없습니다. 가상의 생성 요청이 접수된 직후 응답이 도착하지 않았다면 작업은 이미 존재할 수 있습니다.

이 상태에서 같은 요청을 계속 보내면 같은 보고서가 여러 번 만들어질 가능성을 설계상 검토해야 합니다. 서비스가 제공하는 요청 식별자나 중복 처리 방지 규칙이 있다면 그 계약에 맞춰 사용합니다.

그러한 장치가 없는데 클라이언트만 임의로 완료 여부를 확정하는 것은 어렵습니다. 오류 처리 화면에서도 실패가 확인된 상태와 결과를 아직 모르는 상태를 나누는 편이 정확합니다.

로그에는 재시도 횟수와 연결되는 작업 번호를 남겨 나중에 중복 여부를 조사할 수 있게 합니다.

6. 화면과 운영 지표를 같은 단계로 맞춥니다

사용자 화면은 접수 완료라고 표시하는데 운영 지표는 최종 성공으로 집계하면 같은 사건을 서로 다르게 이해하게 됩니다. 접수 요청 수, 처리 완료 수, 처리 실패 수를 구분해 두면 어느 단계에서 문제가 생겼는지 더 쉽게 볼 수 있습니다.

예를 들어 접수는 평소와 비슷한데 완료 건수가 줄었다면 요청 입구 밖의 처리 과정을 조사할 근거가 생깁니다. 반대로 접수 자체가 줄었다면 사용량 변화나 호출 경로를 먼저 살펴볼 수 있습니다.

숫자는 집계 시점도 중요합니다. 오늘 접수된 작업이 내일 완료되는 구조라면 같은 날짜의 두 수치를 단순 비교하지 않아야 합니다.

어떤 작업 묶음을 대상으로 어떤 상태를 세었는지 지표 설명에 함께 적습니다.

7. 테스트에서는 중간 상태도 확인합니다

최종 결과가 한 번 생성되는지만 시험하면 접수 이후의 사용자 경험을 놓칠 수 있습니다. 가상의 테스트 항목에는 오래 대기하는 작업, 처리 중 실패, 결과 조회 중 연결 오류, 이미 끝난 작업의 재조회 등을 넣을 수 있습니다.

각각의 상황에서 버튼과 안내 문구가 어떤 상태인지 먼저 정해 봅니다. 응답 본문의 필수 값이 빠졌을 때 완료로 오인하지 않는지도 확인합니다.

문서에는 상태 코드뿐 아니라 가능한 업무 상태와 상태가 바뀌는 조건을 적습니다. 클라이언트 담당자와 서버 담당자가 같은 예시 응답을 보고 동일한 화면을 떠올릴 수 있는지 검토하면 좋습니다.

API 계약은 정상 응답 한 장보다 대기와 실패를 포함한 흐름에서 더 분명하게 드러납니다. 문서 예시에는 성공한 작업만 넣지 않고 아직 끝나지 않은 작업 하나도 함께 실어 봅니다.

가상의 R17 작업을 처음 조회했을 때는 대기 중이고 나중에 조회했을 때는 완료라고 적으면 같은 조회 요청이 다른 업무 상태를 전달한다는 점이 드러납니다. 실패 예시에는 사용자가 수정해 다시 요청할 수 있는 정보인지 운영자 확인이 필요한 정보인지 구분합니다.

내부 오류 내용을 그대로 고객에게 노출할 필요는 없지만 문의에 사용할 식별자는 연결할 수 있어야 합니다. 상태 이름이 추가될 때 오래된 클라이언트가 이를 성공으로 오인하지 않는지도 검토합니다.

이런 사례를 계약 문서에 넣으면 상태 코드 표만으로 놓치기 쉬운 화면 분기를 확인하기 좋습니다.

8. 자주 묻는 질문

Q1. 200이면 업무가 완료된 것 아닌가요?

해당 요청이 무엇을 하는지에 따라 판단해야 합니다. 상태 조회가 성공해도 조회한 작업은 아직 처리 중이거나 실패 상태일 수 있습니다.

Q2. 202를 받으면 얼마나 기다려야 하나요?

상태 코드 자체가 고정된 대기 시간을 정해 주지는 않습니다. 서비스가 안내하는 조회 방법과 간격, 처리 지연 안내를 따라야 합니다.

Q3. 타임아웃이면 바로 같은 요청을 보내도 되나요?

원래 요청이 접수되었는지 먼저 확인할 방법이 필요합니다. 중복 처리 방지와 재시도 규칙은 해당 API 계약에 맞춰 적용합니다.

Q4. 업무 실패도 HTTP 성공으로 반환할 수 있나요?

실패한 작업의 상태를 정상 조회하는 응답이라면 가능합니다. 업무 실행 요청과 상태 자원 조회를 구분하고 응답 본문의 의미를 문서로 합의해야 합니다.

참고 자료

• RFC 9110: HTTP Semantics, 202 Accepted