기업지원금 진단 (MCP 도구)
고용24 사전진단과 국세청 사업자상태를 묶어 지원 사업별 신청 가능 여부, 결격 사유와 미확정 항목을 받는 방법입니다.
준비
도구 이름은 subsidy_pack__diagnosis_v1__generate 이며 액션은 subsidy_pack.diagnosis_v1.generate 입니다.이 팩을 사용할 수 있는 상품 권한과 고용24 기관 연동이 필요합니다.
MCP 연결과 고용24 사전진단의 로그인 절차를 먼저 완료하고, 고용24 대표 연동을 확인하세요.팩 호출의 account_link_id 는 무시되므로 특정 연동을 선택하는 용도로 사용할 수 없습니다.
사업자상태는 국세청 사업자상태 조회를 사용합니다. 이 도구는 조회와 진단을 수행하며 지원금 신청서를 제출하지 않습니다.
arguments
| 필드 | 타입 | 필수 | 설명 | 예시 |
|---|---|---|---|---|
| business_management_no | string | 선택 | 진단할 사업장관리번호입니다. 생략하면 고용24 로그인 사업장을 사용합니다. 여러 사업장을 관리한다면 대상 번호를 지정하세요. | 12345678900 |
| bizno | string | 선택 | 국세청 사업자상태를 조회할 사업자등록번호 10자리입니다. 생략하면 사업자 상태를 확인하지 못할 수 있으므로 완전한 진단에는 함께 보냅니다. | 1234567890 |
| programme_keys | array | 선택 | 진단할 지원 사업 코드 목록입니다. 생략하면 현재 진단 대상 사업을 순회합니다. 코드는 고용24 사전진단 API의 사업 목록을 확인합니다. | — |
| application_year | integer | 선택 | 신청연도입니다. 생략하면 현재 연도를 사용합니다. | 2026 |
| output_formats | array | 선택 | 이 결과를 PDF 파일로도 받으려면 적습니다. 예: ["pdf"]. 파일은 artifacts 에 함께 오고, 빼면 데이터만 옵니다. | — |
| API_KEY | - | 받지 않음 | account_link_id 의 다른 철자입니다. 서버가 같은 칸으로 보고 똑같이 처리합니다. | — |
| accountLinkId | - | 받지 않음 | account_link_id 의 다른 철자입니다. 서버가 같은 칸으로 보고 똑같이 처리합니다. | — |
| account_link_id | - | 받지 않음 | 받지 않는 칸입니다. 보내도 무시됩니다. 고용24는 대표 연동을 사용하므로 호출 전에 대표 연동과 로그인 상태를 확인합니다. 사업자상태 조회에는 고객 연동이 필요 없습니다. | — |
| api_key | - | 받지 않음 | account_link_id 의 다른 철자입니다. 서버가 같은 칸으로 보고 똑같이 처리합니다. | — |
| idempotency_key | string | 선택 | 이 실행의 멱등 키입니다(비어 있지 않은 문자열, 앞뒤 공백은 지우고 128자까지 씁니다). 같은 키와 같은 조회 조건으로 다시 부르면 새 작업을 만들지 않고 이전 작업을 그대로 돌려받아 같은 결과가 옵니다. 같은 키로 조회 조건을 바꾸면 조회를 하나도 시작하지 않고 호출이 오류 번호 -32602(error_code IDEMPOTENCY_KEY_CONFLICT)로 끝나니, 같은 요청을 다시 보내는 것이면 처음 보낸 인자 그대로 보내고 새 요청이면 새 키를 쓰세요. 넣지 않으면 서버가 호출마다 새 키를 만들어 매번 새 작업으로 처리합니다. | subsidy-diagnosis-example-001 |
호출 예시
# 사업장번호와 사업자등록번호를 실제 연동 대상 값으로 바꿉니다.
# echo -n "<client_id>:<client_secret>" | base64
export MCP_URL="https://api.xdata.kr/mcp"
export MCP_AUTH_B64="<base64_결과_붙여넣기>"
curl -sS -X POST "$MCP_URL" \
-H "Authorization: Basic $MCP_AUTH_B64" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "subsidy_pack__diagnosis_v1__generate",
"arguments": {
"business_management_no": "12345678900",
"bizno": "1234567890",
"application_year": 2026,
"idempotency_key": "subsidy-diagnosis-example-001"
}
}
}'응답 해석
MCP 성공 결과의 content 에 담긴 JSON을 읽습니다.MCP 오류 처리처럼 최상위 error 와 result.isError 를 먼저 확인하세요.
partial 이 true 이면 일부 조회나 계산이 끝나지 않았습니다.computed 가 null 이면 computed_error.reason 을 확인합니다. computed 가 있어도 business_state.known 이 false 이면 사업자 상태 확인은 완료되지 않았습니다.
신청 가능 사업은 applicable_programmes 에 있습니다.미확정 사업을 적합으로 취급하지 마세요. 폐업이나 휴업이 확인되면 신청 가능 목록은 비어 있습니다. 신청 가능 판정은 지급 확정이 아니며 근로자 요건과 기관 심사가 남아 있습니다.
응답 필드
| 경로 | 형식 | 있음 | 설명 |
|---|---|---|---|
| pack_run_id | string | 항상 | 이 실행의 팩 실행 아이디입니다. 링크가 만료되면 MCP 도구 xdata__job__result 에 이 값을 pack_run_id 로 보내 같은 결과를 다시 읽습니다(새 조회를 만들지 않고 사용 토큰도 쓰지 않습니다). |
| composite | boolean | 항상 | 항상 true 입니다. 일반 도구 결과와 이 칸으로 구분합니다. |
| tool_name | string | 항상 | 호출한 MCP 도구 이름입니다. |
| provider | string | 항상 | 팩의 provider 이름입니다. |
| action | string | 항상 | 팩의 action 이름입니다. |
| idempotency_key | string | 항상 | 이 실행의 멱등 키입니다. arguments 에 idempotency_key 를 넣었으면 그 값(앞뒤 공백을 지우고 128자까지), 넣지 않았으면 서버가 만든 값입니다. |
| partial | boolean | 항상 | 보고가 완전하지 않으면 true 입니다. leg 하나라도 성공하지 못했거나 계산을 하지 못했을 때입니다. true 여도 받은 자료는 그대로 쓸 수 있습니다 - 무엇이 비었는지는 legs 와 computed 가 알려 줍니다. |
| legs | array | 항상 | 고용24 사전진단과 국세청 사업자상태 조회 두 결과입니다. |
| legs[].leg_index | number | 항상 | leg 의 순번입니다(0 부터, 정의 순서). |
| legs[].provider | string | 항상 | 이 leg 이 부른 기관입니다. |
| legs[].action | string | 항상 | 이 leg 이 실행한 원자 액션입니다. |
| legs[].label_ko | string | 항상 | 이 leg 을 화면에 보일 한국어 이름입니다. |
| legs[].status | string | 항상 | 조회 결과 상태로 SUCCEEDED 또는 FAILED 입니다. |
| legs[].job_id | string | null | 항상 | 이 leg 이 실행한 개별 작업의 아이디입니다. 제출하지 못한 leg 은 null 입니다. |
| legs[].result | object | null | 항상 | 원자 조회의 결과 본문입니다. 고용24 사전진단과 공공데이터 사업자상태 조회 문서를 함께 참고합니다. 실패한 조회는 null 입니다. |
| legs[].artifacts | array | null | 항상 | 성공한 leg 의 작업이 낸 파일 목록입니다. 파일을 내지 않았으면 빈 목록이고, 실패했거나 건너뛴 leg 은 null 입니다. 파일은 legs[].result 와 섞이지 않고 이 칸에만 있습니다. |
| legs[].error | object | null | 항상 | 실패한 leg 의 오류입니다. 성공했으면 null 입니다. |
| legs[].error.code | number | 조건부 | 오류 번호입니다(JSON-RPC 코드). |
| legs[].error.message | string | 조건부 | 이 leg 의 오류 문장입니다. 프로그램의 분기에는 code 와 data.error_code 를 쓰고, 문장은 사람이 읽는 용도로만 쓰세요. |
| legs[].error.data | object | null | 조건부 | 오류 종류별 부가 정보입니다. 보통 error_code 가 들어 있고 종류에 따라 다른 칸이 더해집니다. 부가 정보가 없는 오류는 이 칸이 없거나 null 입니다. 시간 초과일 때의 칸은 이 페이지의 시간 초과 절 표에 있습니다. |
| succeeded_count | number | 항상 | 성공한 leg 수입니다. |
| failed_count | number | 항상 | 성공하지 못한 leg 수입니다. |
| computed | object | null | 항상 | 진단 결과를 신청 가능, 결격, 미확정으로 나눈 요약입니다. 고용24 진단 자료가 없거나 계산 시간이 부족하면 null 입니다. |
| computed.as_of | string | 조건부 | 요약을 만든 UTC 시각입니다. |
| computed.business_management_no | string | 조건부 | 고용24 진단에 사용한 사업장관리번호입니다. |
| computed.bizno | string | null | 조건부 | 요청한 사업자등록번호입니다. 생략했으면 null 입니다. |
| computed.application_year | number | 조건부 | 진단 대상 신청연도입니다. |
| computed.catalog_measured_on | string | 조건부 | 진단 사업 목록을 확인한 기준일입니다. |
| computed.business_state | object | 조건부 | 사업자 상태 확인 결과입니다. known 이 false 이면 정상 사업자로 확정해서는 안 됩니다. |
| computed.business_state.known | boolean | 조건부 | 사업자 상태를 확인했는지 나타냅니다. |
| computed.business_state.business_status_ko | string | 조건부 | 국세청 사업자 상태입니다. 조회에 실패하거나 결과가 비었으면 이 칸이 없습니다. |
| computed.business_state.blocks_application | boolean | 조건부 | 폐업 또는 휴업 상태면 true 이며 신청 가능 사업 목록은 비어 있습니다. |
| computed.business_state.reason_ko | string | 조건부 | 사업자 상태를 해석한 안내 문장입니다. |
| computed.summary | object | 조건부 | 사업별 진단 건수입니다. 사업자 상태가 신청을 막으면 applicable_now 는 0 입니다. |
| computed.summary.diagnosed | number | 조건부 | 진단 결과에 포함된 사업 수입니다. |
| computed.summary.applicable_now | number | 조건부 | 현재 신청 가능 목록에 포함된 사업 수입니다. 지급 확정을 뜻하지 않습니다. |
| computed.summary.eligible | number | 조건부 | 적합으로 판정된 사업 수입니다. |
| computed.summary.conditional | number | 조건부 | 입력 또는 심사 조건이 남은 사업 수입니다. |
| computed.summary.ineligible | number | 조건부 | 결격으로 판정된 사업 수입니다. |
| computed.summary.undetermined | number | 조건부 | 판정하지 못한 사업 수입니다. |
| computed.applicable_programmes | array | 조건부 | 적합 및 조건부 사업 목록입니다. 폐업 또는 휴업이면 빈 목록입니다. |
| computed.applicable_programmes[].programme_key | string | 조건부 | 지원 사업 코드입니다. |
| computed.applicable_programmes[].programme_label_ko | string | 조건부 | 지원 사업 이름입니다. |
| computed.applicable_programmes[].category | string | 조건부 | 지원 사업의 분류입니다. |
| computed.applicable_programmes[].verdict | string | 조건부 | 사업별 판정값입니다. 신청 가능 목록에는 eligible 또는 conditional 이 포함됩니다. |
| computed.applicable_programmes[].awaiting_input_count | number | 조건부 | 신청서 입력 후 판정할 항목 수입니다. |
| computed.applicable_programmes[].awaiting_review_count | number | 조건부 | 담당자 심사에서 확정할 항목 수입니다. |
| computed.applicable_programmes[].message_ko | string | 조건부 | 사업별 판정 안내 문장입니다. |
| computed.blocked_programmes | array | 조건부 | 결격 사업 목록입니다. |
| computed.blocked_programmes[].programme_key | string | 조건부 | 지원 사업 코드입니다. |
| computed.blocked_programmes[].programme_label_ko | string | 조건부 | 지원 사업 이름입니다. |
| computed.blocked_programmes[].message_ko | string | 조건부 | 사업별 판정 안내 문장입니다. |
| computed.undetermined_programmes | array | 조건부 | 판정하지 못한 사업 목록입니다. 적합으로 취급하지 않습니다. |
| computed.undetermined_programmes[].programme_key | string | 조건부 | 지원 사업 코드입니다. |
| computed.undetermined_programmes[].programme_label_ko | string | 조건부 | 지원 사업 이름입니다. |
| computed.undetermined_programmes[].message_ko | string | 조건부 | 사업별 판정 안내 문장입니다. |
| computed.undetermined_programmes[].error | string | null | 조건부 | 미확정 판정의 오류 정보입니다. 오류가 없으면 null 입니다. |
| computed.blocking_reasons | object | 조건부 | 결격 항목 이름을 키로, 그 사유에 해당하는 사업 코드 목록을 값으로 담은 객체입니다. |
| computed.legs | array | 조건부 | 진단과 사업자상태 원자 조회의 실행 상태 요약입니다. |
| computed.legs[].action | string | 조건부 | 원자 조회 액션 이름입니다. |
| computed.legs[].status | string | 조건부 | 원자 조회 상태입니다. 결과 자체가 없으면 MISSING 입니다. |
| computed.legs[].job_id | string | null | 조건부 | 원자 조회 작업 아이디입니다. 작업을 만들지 못했으면 null 입니다. |
| computed.legs[].error | object | 조건부 | 실패한 원자 조회의 오류 봉투입니다. 성공한 조회에는 없습니다. |
| computed.coverage_notes_ko | array | 조건부 | 진단 범위와 결과를 해석할 때 확인할 안내 문장 목록입니다. |
| computed_error | object | null | 항상 | 계산을 하지 못했을 때만 값이 있고(computed 는 null), 그 밖에는 null 입니다. |
| computed_error.reason | string | 조건부 | 계산하지 못한 이유입니다. 값마다 뜻과 결과(보고가 partial 로 오는지, 오류로 끝나는지)는 「시간 초과와 계산 실패」 절의 표에 있습니다. |
| computed_error.message | string | 조건부 | 이유를 설명하는 문장입니다. 마감으로 계산을 건너뛴 봉투(deadline_exhausted)는 한국어 안내 문장이고, 계산에 필요한 leg 자료가 없는 봉투(dependency_missing)는 어느 leg 의 결과가 없는지 알리는 한국어 안내 문장입니다. 사람이 읽는 문장이니 프로그램의 분기에는 reason 을 쓰세요. |
| artifacts | array | 항상 | 이 실행이 만든 파일 목록입니다. arguments 에 output_formats 로 형식을 청했을 때만 항목이 생기고, 청하지 않았으면 빈 목록입니다. 항목마다 download_url, name, size_bytes, sha256, expires_at 이 있습니다. 칸의 뜻과 내려받기 주소의 유효 시간은 작업 처리 흐름의 결과 조회(result.artifacts)와 같습니다. 링크가 만료되면 pack_run_id 로 xdata__job__result 를 다시 부릅니다. |
다음 예시는 합성 조회 결과를 실제 응답 생성 코드에 넣어 만든 구조 예시입니다. 실제 사업장의 진단 결과가 아닙니다.
성공 예시
{
"pack_run_id": "prun_01JC8YH8R0E1ABCDEFGHJKMN0P",
"composite": true,
"tool_name": "subsidy_pack__diagnosis_v1__generate",
"provider": "subsidy_pack",
"action": "subsidy_pack.diagnosis_v1.generate",
"idempotency_key": "subsidy-diagnosis-example-001",
"partial": false,
"legs": [
{
"leg_index": 0,
"provider": "work24",
"action": "work24.subsidy.diagnosis.search",
"label_ko": "고용24 사업주 사전진단",
"status": "SUCCEEDED",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN100",
"result": {
"business_management_no": "12345678900",
"application_year": 2026,
"results": [
{
"programme_key": "example_0",
"programme_label_ko": "예시 지원 사업 0",
"category": "예시 분류",
"verdict": "eligible",
"awaiting_input_count": 0,
"awaiting_review_count": 0,
"message_ko": "합성 진단 예시입니다.",
"items": [],
"error": null
},
{
"programme_key": "example_1",
"programme_label_ko": "예시 지원 사업 1",
"category": "예시 분류",
"verdict": "conditional",
"awaiting_input_count": 0,
"awaiting_review_count": 1,
"message_ko": "합성 진단 예시입니다.",
"items": [],
"error": null
},
{
"programme_key": "example_2",
"programme_label_ko": "예시 지원 사업 2",
"category": "예시 분류",
"verdict": "ineligible",
"awaiting_input_count": 0,
"awaiting_review_count": 0,
"message_ko": "합성 진단 예시입니다.",
"items": [],
"error": null
},
{
"programme_key": "example_3",
"programme_label_ko": "예시 지원 사업 3",
"category": "예시 분류",
"verdict": "undetermined",
"awaiting_input_count": 0,
"awaiting_review_count": 0,
"message_ko": "합성 진단 예시입니다.",
"items": [],
"error": "예시 조회 오류"
}
]
},
"artifacts": [],
"error": null
},
{
"leg_index": 1,
"provider": "opendata",
"action": "opendata.nts.status",
"label_ko": "사업자상태",
"status": "SUCCEEDED",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN101",
"result": {
"source_id": "15081808",
"action": "opendata.nts.status",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN101",
"source": {
"id": "15081808",
"org": "국세청",
"license": "공공데이터포털(data.go.kr) 이용 허락 범위에 따릅니다"
},
"license_notes": [
"출처: 국세청 사업자등록 상태 / data.go.kr 15081808",
"라이선스: 공공데이터포털(data.go.kr) 이용 허락 범위에 따릅니다",
"본 기업 리스크 조회 결과는 공공데이터포털 공개 원천을 조합한 참고 정보입니다. 각 응답에 출처 기관·데이터셋 ID를 표시합니다. 원천에 데이터가 없거나 매칭되지 않으면 해당 축은 「해당 없음」 과 「조회 범위 밖」 으로 구분되며 확정 판정·신용평가 대체와 혼동하지 않습니다. Website에서의 팩 체크아웃·결제 경로는 제공하지 않습니다 (콘솔/Admin 전용)."
],
"upstream": {
"status_code": "OK",
"data": [
{
"b_no": "1234567890",
"b_stt": "계속사업자"
}
]
}
},
"artifacts": [],
"error": null
}
],
"succeeded_count": 2,
"failed_count": 0,
"computed": {
"as_of": "2026-10-25T00:00:00Z",
"business_management_no": "12345678900",
"bizno": "1234567890",
"application_year": 2026,
"catalog_measured_on": "2026-09-01",
"business_state": {
"known": true,
"business_status_ko": "계속사업자",
"blocks_application": false,
"reason_ko": "사업자 상태: 계속사업자"
},
"summary": {
"diagnosed": 4,
"applicable_now": 2,
"eligible": 1,
"conditional": 1,
"ineligible": 1,
"undetermined": 1
},
"applicable_programmes": [
{
"programme_key": "example_0",
"programme_label_ko": "예시 지원 사업 0",
"category": "예시 분류",
"verdict": "eligible",
"awaiting_input_count": 0,
"awaiting_review_count": 0,
"message_ko": "합성 진단 예시입니다."
},
{
"programme_key": "example_1",
"programme_label_ko": "예시 지원 사업 1",
"category": "예시 분류",
"verdict": "conditional",
"awaiting_input_count": 0,
"awaiting_review_count": 1,
"message_ko": "합성 진단 예시입니다."
}
],
"blocked_programmes": [
{
"programme_key": "example_2",
"programme_label_ko": "예시 지원 사업 2",
"message_ko": "합성 진단 예시입니다."
}
],
"undetermined_programmes": [
{
"programme_key": "example_3",
"programme_label_ko": "예시 지원 사업 3",
"message_ko": "합성 진단 예시입니다.",
"error": "예시 조회 오류"
}
],
"blocking_reasons": {},
"legs": [
{
"action": "work24.subsidy.diagnosis.search",
"status": "SUCCEEDED",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN100"
},
{
"action": "opendata.nts.status",
"status": "SUCCEEDED",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN101"
}
],
"coverage_notes_ko": [
"기관 화면은 확정된 부적합만 부적합으로 보여 주고 미확정을 적합처럼 표시합니다. 이 진단은 미확정 항목을 적합으로 보지 않습니다.",
"진단은 사업장 단위로 합니다. 사업장이 여러 개면 사업장마다 따로 진단해 주세요.",
"체납 판정은 기관 전산 반영 시점을 따릅니다. 이미 납부하셨더라도 며칠간 체납으로 남을 수 있고, 연계 사이트마다 반영 시점이 달라 서로 다르게 보일 수 있습니다.",
"사전진단 단계가 없는 사업 3개와 아직 확인하지 못한 사업 3개는 이 진단에 포함되지 않습니다. 결격 사유가 접수 이후에 드러날 수 있습니다.",
"신청 가능은 결격 사유가 확인되지 않았다는 뜻이며 지급을 보장하지 않습니다. 지급은 대상 근로자 요건과 심사를 함께 통과해야 합니다.",
"미확정 항목은 두 종류입니다. '신청서를 작성하면 판정되는 항목'은 아직 입력이 없어서 판정하지 못한 것이고, '심사에서 확정되는 항목'은 담당자 심사를 기다립니다. 어느 쪽도 결격이 아니므로 신청 가능 사업에서 제외하지 않습니다."
]
},
"computed_error": null,
"artifacts": []
}고용24 진단 자료가 없는 경우
{
"pack_run_id": "prun_01JC8YH8R0E1ABCDEFGHJKMN0P",
"composite": true,
"tool_name": "subsidy_pack__diagnosis_v1__generate",
"provider": "subsidy_pack",
"action": "subsidy_pack.diagnosis_v1.generate",
"idempotency_key": "subsidy-diagnosis-example-001",
"partial": true,
"legs": [
{
"leg_index": 0,
"provider": "work24",
"action": "work24.subsidy.diagnosis.search",
"label_ko": "고용24 사업주 사전진단",
"status": "FAILED",
"job_id": null,
"result": null,
"artifacts": null,
"error": {
"code": -32602,
"message": "고용24 연동 계정이 없습니다. https://console.xdata.kr/credentials?link=1&priority=work24 에서 인증서를 연결한 뒤 이 도구를 다시 호출하세요. 연결은 호출할 때마다 새로 확인하므로 따로 다시 시작할 필요가 없습니다.",
"data": {
"error_code": "PRIMARY_ACCOUNT_LINK_NOT_FOUND",
"link_url": "https://console.xdata.kr/credentials?link=1&priority=work24"
}
}
},
{
"leg_index": 1,
"provider": "opendata",
"action": "opendata.nts.status",
"label_ko": "사업자상태",
"status": "SUCCEEDED",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN101",
"result": {
"source_id": "15081808",
"action": "opendata.nts.status",
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMN101",
"source": {
"id": "15081808",
"org": "국세청",
"license": "공공데이터포털(data.go.kr) 이용 허락 범위에 따릅니다"
},
"license_notes": [
"출처: 국세청 사업자등록 상태 / data.go.kr 15081808",
"라이선스: 공공데이터포털(data.go.kr) 이용 허락 범위에 따릅니다",
"본 기업 리스크 조회 결과는 공공데이터포털 공개 원천을 조합한 참고 정보입니다. 각 응답에 출처 기관·데이터셋 ID를 표시합니다. 원천에 데이터가 없거나 매칭되지 않으면 해당 축은 「해당 없음」 과 「조회 범위 밖」 으로 구분되며 확정 판정·신용평가 대체와 혼동하지 않습니다. Website에서의 팩 체크아웃·결제 경로는 제공하지 않습니다 (콘솔/Admin 전용)."
],
"upstream": {
"status_code": "OK",
"data": [
{
"b_no": "1234567890",
"b_stt": "계속사업자"
}
]
}
},
"artifacts": [],
"error": null
}
],
"succeeded_count": 1,
"failed_count": 1,
"computed": null,
"computed_error": {
"reason": "dependency_missing",
"message": "work24 사업주 사전진단 결과가 없어 지원 가능 사업을 판정할 수 없습니다."
},
"artifacts": []
}계산 실패와 재확인
| reason | 결과 | 대응 |
|---|---|---|
| deadline_exhausted | 보고가 오고 partial | 호출 전체 마감 시간이 다 돼 계산을 건너뛰었습니다. 받은 자료는 legs 에 있고 봉투는 partial 로 옵니다(computed 는 null). |
| dependency_missing | 보고가 오고 partial | 계산에 필요한 leg 자료가 없습니다. 받은 자료는 legs 에 있고 봉투는 partial 로 옵니다. |
| validation_failed | 오류로 끝남 | 계산 중 값 검증에서 실패했습니다(우리 쪽 결함). 봉투를 주지 않고 오류로 끝나며 받은 leg 결과는 오류의 data 에 실립니다. |
| builder_raised | 오류로 끝남 | 계산 중 예외가 났습니다(우리 쪽 결함). 봉투를 주지 않고 오류로 끝나며 받은 leg 결과는 오류의 data 에 실립니다. |
시간 초과
호출 전체 대기 한도는 90초이고 원자 조회 하나의 대기 한도는 60초입니다.시간 초과가 기관 작업의 취소를 뜻하지는 않습니다. 오류의 result_tool_call 이 있으면 name 과 arguments 를 그대로 사용해 기존 결과를 읽습니다.
원자 조회 시간 초과 정보
| 필드 | 설명 |
|---|---|
| job_id | 시간 안에 끝나지 않은 작업의 아이디입니다. 작업은 서버에서 계속 돌 수 있습니다. |
| timeout_seconds | 이 조회를 기다린 한도(초)입니다. 조회 하나의 최대 대기 시간이고, 호출 전체 마감까지 남은 시간이 그보다 짧으면 남은 시간이라 더 작습니다(소수일 수 있습니다). |
| safe_to_retry | 두 원자 조회는 읽기 작업입니다. 오류에 제공된 결과 조회 호출로 기존 작업을 먼저 확인합니다. |
| status_url | 그 작업의 결과를 GET 으로 읽을 수 있는 주소입니다(REST 로 연동한 서비스에서 같은 API 키를 씁니다). |
| result_tool_call | 그 작업의 결과를 읽는 MCP 도구 호출입니다(name 과 arguments 를 그대로 부르면 됩니다). 작업을 다시 돌리지 않고 사용 토큰도 쓰지 않으며, 아직 돌고 있으면 잠시 기다렸다가 알려 줍니다. |
호출 전체 시간 초과 정보
| 필드 | 설명 |
|---|---|
| error_code | 항상 COMPOSITE_TIMEOUT 입니다. 이 값으로 호출 전체 마감을 가려냅니다. |
| timeout_seconds | 호출 전체 대기 한도(초)입니다. |
| phase | 마감이 된 단계의 이름입니다(진단용 - 분기에 쓰지 않습니다). |
| job_id | 제출한 작업의 아이디입니다. 제출하지 못했으면 이 칸이 없습니다. |
| result_tool_call | 그 작업의 결과를 읽는 MCP 도구 호출입니다(name 과 arguments 를 그대로 부르면 됩니다). 작업을 다시 돌리지 않고 사용 토큰도 쓰지 않습니다. job_id 가 있을 때만 옵니다. |
| submitted | 그 조회의 작업을 이미 제출했는지 알려 줍니다. true 면 job_id 가 함께 옵니다. |
멱등키와 비용
같은 요청을 재시도할 때는 같은 idempotency_key 와 같은 인자를 사용합니다.조회 조건이 바뀌면 새 키를 사용하세요. 키가 없으면 호출마다 새 작업이 만들어질 수 있습니다. 팩 및 원자 조회의 권한과 사용 한도가 적용되며, 권한 거절을 기관 조회 성공으로 취급하지 않습니다.
멱등키 충돌 예시
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "같은 idempotency_key 로 내용이 다른 요청이 이미 들어왔습니다. 같은 요청을 다시 보내는 것이면 처음 보낸 인자 그대로 보내고, 새 요청이면 idempotency_key 를 새 값으로 바꾸거나 아예 넣지 마세요(넣지 않으면 서버가 만듭니다).",
"data": {
"error_code": "IDEMPOTENCY_KEY_CONFLICT",
"safe_to_retry": false
}
}
}