HTTP 상태 코드: 응답 분류와 애플리케이션 성공의 구분
작성: Ai Flowi · 게시일
HTTP 상태 코드는 HTTP 요청이 어떻게 처리되었는지 나타내는 세 자리 응답 값입니다. 첫 번째 숫자는 큰 범주의 응답 분류를 나타내며, 개별 코드는 더 구체적인 의미를 전달합니다. 애플리케이션 수준의 성공을 확인하려면 예상한 본문, 의도한 처리 결과, 응답에서 노출하는 정보를 별도로 점검해야 합니다.
호출자는 200 응답을 받더라도 잘못된 레코드, 불완전한 데이터 모음, 비공개 필드를 받을 수 있습니다. 반대로 오류 응답이 요청 거부를 정확히 설명하면서도 호출자가 보아서는 안 되는 세부 정보를 노출할 수 있습니다. 상태 코드는 엔드포인트 계약을 확인하는 여러 근거 중 하나로 다루어야 합니다.
먼저 응답 분류를 확인합니다
응답 분류는 다음에 무엇을 확인할지 판단하는 데 도움이 됩니다. 그러나 개별 코드의 의미, 요청 메서드, API에 문서화된 응답 스키마를 대신하지는 않습니다. 이 글은 응답을 해석하는 안내이며, 모든 상태 코드를 망라한 목록은 아닙니다.
| 분류 | 일반적인 의미 | 호출자가 확인할 질문 |
|---|---|---|
| 1xx: 정보 응답 | 요청 처리에 관한 중간 정보입니다. | 최종 응답이 도착했습니까? |
| 2xx: 성공 응답 | HTTP 수준에서 요청을 성공적으로 수신하고 이해하여 수락했습니다. | 이 응답으로 애플리케이션의 처리 결과를 확정할 수 있습니까? |
| 3xx: 리다이렉션 | 요청을 완료하려면 추가 조치가 필요하며, 캐시 관련 처리도 포함됩니다. | 리다이렉션을 따라가거나 캐시된 표현을 사용해야 합니까? |
| 4xx: 클라이언트 오류 | 제출된 요청을 그대로 처리할 수 없습니다. | 요청, 인증 정보, 상태 조건 중 무엇을 확인해야 합니까? |
| 5xx: 서버 오류 | 서버가 유효해 보이는 요청을 처리하지 못했습니다. | 무엇이 실패했으며, 작업의 최종 처리 결과를 알고 있습니까? |
응답이 없으면 관찰된 HTTP 상태 코드도 없습니다. 연결 실패나 호출자의 시간 초과는 임의로 500을 부여하지 말고 ‘결과 알 수 없음’으로 기록해야 합니다. 쓰기 요청이 이미 대상에 도달했을 가능성이 있다면 재시도 전에 이 불확실성을 고려해야 합니다.
주요 API 응답 코드의 차이를 구분합니다
200 OK는 HTTP 처리가 성공했음을 나타내지만, 본문의 의미는 작업에 따라 달라집니다. 202 Accepted는 처리를 수락했다는 뜻이며 완료를 확정하지는 않습니다. 204 No Content는 응답 콘텐츠 없이 처리가 성공했음을 뜻합니다. 이 응답에 JSON 본문을 요구하는 것은 잘못된 점검입니다.
304 Not Modified는 조건부 요청과 기존 표현의 사용에 관한 코드입니다. 새 데이터 모음을 담은 응답은 아닙니다. 리다이렉션 응답도 신중하게 해석해야 합니다. 원래 대상에서 받은 응답과 리다이렉션을 따른 뒤 받은 응답은 서로 다른 관찰입니다.
400은 잘못된 요청에 관한 코드입니다. 401은 인증에 관한 코드이고, 403은 거부를 나타냅니다. 404만으로는 여러 단계로 구성된 애플리케이션 내부에서 어떤 리소스가 없었는지 알 수 없습니다. 429는 요청이 너무 많다는 뜻입니다. 서버 측 오류의 예로는 내부 오류를 나타내는 500과 잘못된 업스트림 응답을 나타내는 502가 있습니다. 어느 코드도 앞서 시도한 쓰기가 아무런 영향을 주지 않았음을 보장하지 않습니다.
본문이 잘못된 가상 200 응답은 어떻게 되나요?
가상의 읽기 엔드포인트가 요청한 항목에 대해 정확히 두 개의 공개 필드인 item_id와 state를 제공한다고 가정합니다. 요청 대상은 sample-A 항목입니다. 계약에 따르면 완료된 결과는 같은 항목을 식별하고 합의된 상태 값을 사용해야 합니다.
{"http_status":200,"content_type":"application/json","body":{"item_id":"sample-B","state":"ready"}}이 예시는 해석 연습을 위해 만든 관찰이며, 실제로 기록된 엔드포인트 응답이 아닙니다. HTTP 상태와 콘텐츠 유형은 적절해 보이지만 식별자가 잘못되었습니다. 호출자는 sample-B를 sample-A의 근거로 표시하지 말고 애플리케이션 결과를 거부해야 합니다.
| 가상 관찰 | HTTP 분류 | 본문 판정 | 처리 결과의 근거 | 정보 노출 판정 |
|---|---|---|---|---|
| sample-A를 읽었는데 sample-B를 반환함 | 200: 성공 분류 | 요청한 항목과 일치하지 않음 | 쓰기 작업이 필요하지 않음 | 이 예시에는 추가 필드가 없음 |
| 쓰기에 ‘기록됨’이라고 응답했지만 대상에 일치하는 레코드가 없음 | 200: 성공 분류 | 제안된 응답 형식과 일치함 | 이 예시의 즉시 조회 가능 가정에서 완전한 재조회 확인에 실패함 | 표시된 정보 유출은 없음 |
| 작업 제출이 작업 참조를 반환함 | 202: 수락됨 | 제출 계약과 일치함 | 완료는 아직 대기 중임 | 허용된 공개 필드를 확인해야 함 |
| 거부된 요청에 비공개 내부 참조가 포함됨 | 4xx: 클라이언트 오류 분류 | 거부를 정확히 설명할 수 있음 | 쓰기를 시도했다면 별도로 확인해야 함 | 공개 응답 계약을 위반함 |
쓰기의 경우 계약에서 대상 조회로 처리 결과를 언제, 어떻게 확인할 수 있는지 정의해야 합니다. 불완전한 조회, 지연된 갱신, 다른 대상의 조회로는 쓰기가 이루어지지 않았다고 확정할 수 없습니다. ‘본문이 올바름’과 ‘처리 결과가 확인됨’을 별도의 결론으로 유지해야 합니다.
제공된 Sheet JSON API 테스트가 실제로 보여 주는 범위
상태: 테스트 완료. Sheet as JSON API 레시피에는 AI Flowi Workflow 1.9.2에서 2026년 10월 9일에 테스트하여 26개 사례 중 25개 통과
한 결과가 기록되어 있습니다. 읽기 전용 Google Sheet 엔드포인트에 대한 테스트이며, API 신뢰성 전반의 벤치마크는 아닙니다.
예상된 404 응답에서 비공개 식별자가 노출된 근거는 레시피의 T20을 확인하고, 플랫폼의 실패 경계는 웹훅 오류 처리를 확인해야 합니다. 상태 코드 해석에서 얻는 교훈은 엔드포인트 승인보다 범위가 좁습니다. 거부가 올바르게 분류되었더라도 정보 노출 여부를 판정해야 합니다.
따라서 위의 가상 표에서 거부된 요청에는 두 가지 판단이 필요합니다. 거부가 요청 계약에 부합했는지, 반환된 필드가 허용되었는지를 각각 확인해야 합니다. 첫 번째 판단이 통과해도 두 번째 판단의 실패는 없어지지 않습니다. 예상된 상태에 하나의 정상 표시를 부여하지 말고 두 판단을 모두 기록해야 합니다.
AI Flowi Workflow에서 상태 코드를 해석하는 위치
상태: 문서화됨. 외부로 보내는 요청의 컴포넌트 계약은 API Request 참조 문서에서 다룹니다. 해당 인터페이스는 카탈로그에 문서화되어 있으나 Ai Flowi가 운영 환경에서 테스트하지 않았습니다
.
HTTP 응답을 판정할 때는 어느 응답에 대한 판정인지 식별해야 합니다. 게이트웨이의 거부, 원래 엔드포인트의 리다이렉션, 리다이렉션 이후 대상의 응답은 별개의 이벤트입니다. 호출자가 최종 200을 관찰했더라도 같은 항목에 관한 이벤트라는 이유로 그 값을 앞선 거부에 연결해서는 안 됩니다.
sample-A 연습에서는 요청한 항목을 관찰된 코드 및 본문 판정과 함께 보관해야 합니다. 이후 응답이 sample-A를 올바르게 식별하더라도 앞선 sample-B 불일치는 실패한 관찰로 유지하고, 이후 응답을 독립적으로 평가해야 합니다. 이렇게 해야 최종적으로 올바른 결과가 나왔다는 이유로 호출자에게 이미 전달된 잘못된 응답이 가려지지 않습니다.
흔한 해석 오류
- 작업이 수락되었을 뿐인데 모든 2xx 응답을 ‘업무 완료’로 간주합니다.
- JSON 문법만 확인하고 요청한 식별자, 허용된 필드, 완전성을 놓칩니다.
- 워크플로 내부의 404를 공개 엔드포인트 주소가 없다는 증거로 간주합니다.
- 예상된 상태 코드라는 이유로 가공되지 않은 오류 세부 정보를 표시합니다.
- 성공 응답을 받지 못했다는 이유만으로 결과가 불확실한 쓰기를 반복합니다.
실행 가능한 응답 및 처리 결과 확인 방법은 API 테스트를 참고합니다. 관련 용어로는 할당량 해석을 다루는 API 요청 제한과 데이터 모음 응답의 완전성을 확인하는 API 페이지네이션이 있습니다.