RCA: ForgeAgents - Error: API Error 401 on manifest endpoint

Overview#

What Happened#

2026-05-07 01:26:24 UTC에 cupixworks-any-room-agent 서비스(ap-southeast-2 리전)에서 Autodesk Forge/APS Model Derivative API의 manifest 엔드포인트 호출 시 401 Unauthorized 에러가 1건 발생했다. room extraction 과정에서 BIM 파일의 manifest를 가져오려 할 때 인증이 거부되었다.

Quick Facts#

Timeline#

1. 2026-05-07T01:26:24Z — SQS 메시지 수신 후 room extraction 시작, Forge manifest API 호출 시 401 에러 발생
2. 2026-05-07T01:26:24Z — BaseService::handlingMessageErrors에서 "undefined error"로 기록
3. 2026-05-07 — RCA 분석 수행

Error Log#

[Datadog Logs](https://app.datadoghq.com/logs?query=service%3Acupixworks-any-room-agent%20status%3Aerror%20%40environment%3Aproduction%20%22ForgeAgents%20-%20Error%3A%20%7B%20code%3A%20102%2C%20message%3A%20API%20Error%3A%20401%20-%20Request%20failed%20with%20status%20code%20401%20(URL%22&from_ts=1778113560000&to_ts=1778120820000&live=false)

ForgeAgents - Error: { code: 102, message: API Error: 401 - Request failed with status code 401 (URL: manifest/dXJuOmFkc2sud2lwcHJvZGFuejpmcy5maWxlOnZmLnNwQUdnVFduUnR1M2RYbWJPRW9jZ2c_dmVyc2lvbj04) }

Impact#

• Service: cupixworks-any-room-agent
• 발생 횟수: 1
• 최초 발생: 2026-05-07T01:26:24.238Z
• 최근 발생: 2026-05-07T01:26:24.238Z

Root Cause Summary#

Autodesk Forge/APS Model Derivative API의 manifest 엔드포인트 호출 시 OAuth2 client credentials로 발급받은 access token이 해당 URN(urn:adsk.wipprodanz:fs.file:vf.spAGgTWnRtu3dXmbOEocgg?version=8)에 대한 접근 권한이 없어 401 Unauthorized가 반환되었다. URN의 wipprodanz prefix는 Autodesk ANZ(호주/뉴질랜드) 데이터 센터의 리소스를 가리키며, 서비스에 설정된 Forge app credentials가 해당 리전 또는 프로젝트에 대한 접근 권한을 갖지 않을 가능성이 높다.

Technical Analysis#

Code Path#

• Entry point: room-service.ts:179 — runRoomExtractor() 호출

private runRoomExtractor = async (cpBim: CPBim): Promise<void> => {
    const roomExtractorResults = await this.roomExtractManager.execute({
        apiConfig: {
            clientId: Environment.ADF_CLIENT_ID,
            clientSecret: Environment.ADF_CLIENT_SECRET,
        },
        urn: cpBim.forgeUrn,
        formatType: cpBim.forgeFormatType,
        region: cpBim.forgeRegion
    });
};

• Child process 호출: room-extractor.process.ts:40 — ForgeAgent.extract() 실행

const result = await ForgeAgent.extract(params.apiConfig, params.urn, {
    extractRoom: true,
    extractMeta: true,
    region: params.region
});

• 인증 및 manifest 조회: @cupix/forge-utils model-data.js:133 — manifest URL 구성

async getManifest(derivativeUrn) {
    return this.get(`manifest/${derivativeUrn}`, {}, ReadTokenScopes, true);
}

• Failure point: @cupix/forge-utils forge-client.js:84 — HTTP 401 응답 처리

case 401:
    throw new ForgeUtilsError(ErrorCode.API_UNAUTHORIZED, message);

• 에러 변환: @cupix/forge-agents app.js:92 — ForgeAgentError 코드 102로 변환 후 로깅

cplogger.error(`ForgeAgents - Error: { code: ${errorResponse.Error}, message: ${errorResponse.ErrorMessage} }`);

기대 동작: ADF_CLIENT_ID/ADF_CLIENT_SECRET로 OAuth2 token을 발급받고, 해당 token으로 manifest 엔드포인트 접근 시 200 OK 응답과 함께 manifest JSON을 수신해야 함.

실제 동작: Token 발급은 성공했으나(401이 token 엔드포인트가 아닌 manifest 엔드포인트에서 발생), manifest 접근 시 401 Unauthorized 반환. 이는 token의 scope 또는 해당 Forge app의 프로젝트 접근 권한 부족을 의미.

Log Evidence#

사용한 Datadog 쿼리:

service:cupixworks-any-room-agent status:error @environment:production

핵심 로그 항목:

[2026-05-07T01:26:24Z] ForgeAgents - Error: { code: 102, message: API Error: 401 - Request failed with status code 401 (URL: manifest/dXJuOmFkc2sud2lwcHJvZGFuejpmcy5maWxlOnZmLnNwQUdnVFduUnR1M2RYbWJPRW9jZ2c_dmVyc2lvbj04) }

[2026-05-07T01:26:24Z] BaseService::handlingMessageErrors | Error and message object - {"error":"undefined error","sqsMessage":{"MessageId":"e60684ff-427c-4dc4-bf95-3bf465f6731a","Attributes":{"ApproximateReceiveCount":"1"}}}

• 동일 시간대(00:26~02:00 UTC)에 다른 ForgeAgents 에러는 발견되지 않음 — 단발성 이벤트
• ApproximateReceiveCount: 1 — SQS 메시지의 첫 번째 수신 시도에서 실패함 (재시도 미확인)
• URN을 base64 디코딩하면 urn:adsk.wipprodanz:fs.file:vf.spAGgTWnRtu3dXmbOEocgg?version=8 — ANZ 리전 리소스

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• 해당 URN(urn:adsk.wipprodanz:fs.file:vf.spAGgTWnRtu3dXmbOEocgg?version=8)이 속한 Autodesk 프로젝트가 현재 설정된 Forge app(ADF_CLIENT_ID)에 프로비저닝되어 있는지 확인
• ANZ 리전 프로젝트에 대한 접근 권한이 Forge app에 부여되지 않았다면 Autodesk 관리 콘솔에서 권한 추가

단기 개선 (1주 이내)#

• room-service.ts:179에서 ForgeAgent 호출 전, 해당 URN의 리전(cpBim.forgeRegion)에 맞는 credentials가 설정되어 있는지 사전 검증 로직 추가
• 401 에러 시 에러 메시지에 URN 디코딩 결과와 리전 정보를 포함하여 디버깅 용이성 개선

장기 개선 (재발 방지)#

• 리전별 Forge app credentials 분리 또는 멀티 리전 접근 권한을 가진 단일 app 구성
• BIM 파일 등록 시점에 해당 URN에 대한 manifest 접근 가능 여부를 사전 검증하는 health check 도입

Monitoring#

• Forge API 401 에러 빈도 추적:

service:cupixworks-any-room-agent "ForgeAgents - Error" "401"

• URN 리전별 에러 분포 대시보드 구성 (wipprodanz, wipprodemea, wipprod 등)

Risk Assessment#

• Risk level: low
• 예상 복잡도: standard
• 단발성 이벤트이며 특정 ANZ 리전 리소스에 국한됨. 서비스 전반에 영향 없으나, 같은 조건의 BIM 파일이 추가될 경우 반복 발생 가능.