202 Accepted 뒤에도 끝나지 않았다: 비동기 API 완료 확인법

AI 자동화가 보고서 생성 API를 호출했고 202 Accepted를 받았다. 이제 사용자에게 “보고서가 완성됐다”고 알려도 될까? 202는 처리를 접수했다는 응답이다. 같은 작업의 상태를 조회하고, 문서가 정한 성공 상태와 실제 결과를 확인한 뒤 완료를 알려야 한다. 작업 ID가 생긴 것과 결과물이 생긴 것을 분리하는 것이 출발점이다.

이 글은 오래 걸리는 비동기 API를 자동화에 연결하는 담당자를 위한 설명이다. 공식 HTTP 표준과 장기 실행 작업 문서를 참고했다. 뒤의 보고서 사례와 판단표는 작성자의 가상 예시이며 특정 API를 호출해 시험한 결과가 아니다.

접수 응답과 작업 결과는 다른 질문에 답한다

RFC 9110의 202 정의는 요청이 처리 대상으로 받아들여졌지만 처리가 끝나지 않았다고 설명한다. 나중에 실제 처리가 허용되지 않을 수도 있다. 응답은 현재 상태와 상태를 확인할 수 있는 수단을 안내하는 것이 바람직하다. 따라서 202만 보고 실행 성공을 확정하거나, 실패 결과가 안 보인다는 이유로 성공으로 채우면 안 된다.

여기서 HTTP 응답과 업무 상태를 따로 읽어야 한다. Azure의 비동기 요청·응답 패턴에는 상태 조회가 HTTP 200을 반환하면서 본문에는 아직 진행 중인 상태를 담는 방식이 나온다. 이때 200은 상태 조회가 정상 응답했다는 뜻이다. 보고서가 완성됐는지는 본문의 상태를 읽어야 한다. 모든 API가 이 형식을 쓰는 것은 아니므로 실제 문서의 완료 조건을 우선한다.

작업 ID, 상태, 결과, 오류를 따로 보관한다

다음 네 항목은 같은 값의 다른 이름이 아니다. 작업 ID 또는 operation name은 같은 실행을 다시 찾는 열쇠다. 상태는 그 실행이 진행 중인지 끝났는지 알려 준다. 결과는 성공한 실행이 만든 산출물이나 대상 식별자다. 오류는 실패한 실행의 이유와 범위를 설명한다. 작업 ID를 결과 파일 ID처럼 사용하면 후속 전송이 너무 일찍 시작될 수 있다.

Google의 Operation 정의를 예로 들면 name은 원래 서비스를 함께 알아야 식별할 수 있는 이름이고, done=false는 진행 중이다. done=true는 종료를 뜻하며 성공 응답인지 오류인지 더 읽어야 한다. 결과 제공 방식의 예외도 있으므로 이 필드명을 모든 제품의 공통 규격처럼 적용하지 않는다.

가상 사례: 보고서 작업은 계속되는데 화면 대기만 끝났다

가상의 보고서 API가 요청을 받고 작업 op-report-a와 상태 주소를 돌려줬다고 하자. 자동화는 상태를 조회했지만 아직 처리 중이었고, 화면에서 기다리기로 한 시간이 끝났다. 이 API가 실제 지원하는 기능을 가정한 사례일 뿐 특정 서비스의 응답값은 아니다.

이때 “보고서 생성 실패”로 확정하고 새 생성 요청을 보내면, 먼저 접수한 작업과 새 작업이 함께 실행될 수 있다. 적절한 표시는 “작업 접수 확인, 마지막 조회에서는 진행 중, 결과 미확인”이다. 사용자 화면의 대기 종료와 서버 작업의 종료를 분리해 같은 작업을 나중에 다시 확인한다. 재실행 판단은 기존 재시도 정책의 안전 조건과 연결하되, 이 글의 중심은 새 요청을 보내는 방법이 아니라 접수한 작업을 끝까지 식별하는 방법이다.

이후 성공 상태와 결과 파일 위치가 확인됐다면 요청한 보고서의 대상 기간과 파일을 맞춘다. “파일 생성”만 맡긴 작업이면 확인 범위도 거기에 맞춘다. 보고서를 이메일로 전달하는 일까지 맡겼다면 파일 생성 확인만으로 전송 완료를 선언할 수 없다. API 작업의 완료 조건과 전체 업무의 완료 조건을 각각 정해야 한다.

폴링에는 간격과 끝나는 조건을 함께 둔다

Azure 패턴은 상태 주소를 알려 주는 Location과 과도한 조회를 줄이는 Retry-After를 제안한다. 이를 모든 202 응답이 반드시 제공한다고 가정해서는 안 된다. 실제 서비스가 안내하는 조회 방식·간격·제한을 먼저 따른다. 작업이 많다면 화면마다 별도 반복 조회를 붙여 호출 수를 늘리는 구조도 살펴야 한다.

작성자가 제안하는 운영 규칙은 단순하다. 종료 상태가 확인되면 반복 조회를 끝낸다. 아직 진행 중이면 문서가 허용하는 간격으로 같은 작업을 조회한다. 일시적인 조회 오류는 작업 자체의 실패와 분리한다. 인증·대상 식별 오류가 나면 그것부터 바로잡고, 정해 둔 관측 기한까지 결과를 모르면 미확인 상태와 다음 담당을 남긴다. 관측을 멈췄다고 서버 작업을 취소한 것은 아니다.

상태 주소의 404도 무조건 작업 실패로 읽지 않는다. 보존 기간 만료, 잘못된 작업 식별자, 결과가 만들어지기 전 대상 주소를 조회하는 구현 등 문맥이 다를 수 있다. 해당 API 문서와 기존 실행 기록으로 범위를 좁힌다. 불명확한 응답을 해소하려고 원래 생성 요청을 반복하는 것은 상태 확인을 대신하지 않는다.