오류 코드
실패한 요청은 error 객체로 답합니다. 코드로 분기하고, 재시도 여부는 응답이 알려 줍니다.
오류 응답에는 error 객체가 있고, code 로 프로그램이 분기합니다.message 는 사람이 읽는 설명이라 로그와 서비스문의에 씁니다.
retryable 이 true 면 같은 요청을 다시 보낼 의미가 있고, false 면 요청이나 설정을 고쳐야 합니다.같은 code 안에서 상황을 더 가르고 싶을 때만 선택 필드 reason 을 봅니다.
사유 칸이 없는 응답 (HTTP 429)
{
"error": {
"code": "POLICY_QUOTA_EXCEEDED",
"message": "오늘 사용 가능한 토큰을 모두 사용하였습니다. 매일 0시(한국 시간)에 자동 충전되며, 추가가 필요하시면 콘솔에서 충전하거나 상위 요금제로 변경하실 수 있습니다.",
"retryable": false,
"provider_error_ref": null,
"trace_id": "trc_5f0c2a9e8d7b4c1f9a3e6b2d4c8f1a07"
}
}reason 이 붙는 응답 (HTTP 403)
{
"error": {
"code": "POLICY_ENV_FORBIDDEN",
"message": "데모 환경은 사용 신청이 승인된 뒤 쓸 수 있습니다. 콘솔 프로필의 환경 메뉴에서 신청해 주세요.",
"retryable": false,
"provider_error_ref": null,
"trace_id": "trc_5f0c2a9e8d7b4c1f9a3e6b2d4c8f1a07",
"reason": "demo_access_not_approved"
}
}오류 본문의 모양
| 본문 모양 | 이럴 때 | error 를 읽는 곳 |
|---|---|---|
| {"error": {...}} | 오류 응답의 기본 모양입니다. 인증, 권한, 요금제, 환경, 한도 검사에서 거절된 요청과 작업 제출과 조회 오류가 모두 이 모양이고, 위 예시가 그렇습니다. Idempotency-Key 를 빠뜨렸을 때의 IDEMPOTENCY_KEY_REQUIRED 나 없는 작업을 조회할 때의 JOB_NOT_FOUND 도 같습니다. | error.code |
| {"error": {..., "fields": [...]}} (HTTP 422) | 요청 본문의 필드 형식이 틀렸을 때입니다(필수 필드 빠짐, 문자열이어야 할 값이 객체나 숫자). error.code 는 VALIDATION_INVALID_FIELD 이고, error.fields 배열의 각 항목이 어느 필드가 왜 틀렸는지 알려 줍니다. 보낸 값은 되돌려 주지 않습니다. | error.code, 필드별 안내는 error.fields 항목의 loc(위치)와 msg(이유) |
| {"error": {...}, "next": {...}} (HTTP 403) | 사람이 콘솔에서 풀어야 하는 거절일 때입니다. 갱신된 이용약관에 다시 동의해야 할 때(COMPLIANCE_TOS_VERSION_OUTDATED)와 조직이 정지되거나 폐쇄됐을 때(AUTHZ_FORBIDDEN, reason organization_not_active)입니다. next 에는 사용자에게 전할 문장(say_to_user)과 열 화면 주소(action_url)가 있고, 칸은 MCP 의 다음 행동 안내와 같습니다. | error.code, 다음 할 일은 next |
| {"detail": "문자열"} | 없는 주소의 404 처럼 오류 코드가 없는 응답입니다. error 는 없습니다. | HTTP 상태와 detail 문장을 그대로 기록 |
코드에서는 본문 최상위 error 를 읽으면 됩니다. error 가 없으면(없는 주소의 404 등) HTTP 상태와 detail 문장을 그대로 기록합니다.
응답 필드
| 필드 | 설명 |
|---|---|
| code | 아래 표에 있는 값 중 하나입니다. 분기는 이 값으로 합니다. |
| message | 사람이 읽는 문장입니다. 키·권한·요금제·환경·한도·동의 관련 거절은 바로 읽을 수 있는 한국어로 오고, 그 밖의 오류는 원인을 적은 기술 문구(영문일 수 있음)로 올 수 있습니다. 문구는 바뀔 수 있어 분기에 쓰지 않습니다. 최종 사용자 화면에는 code 에 맞춘 자체 문구를 보여 주세요. |
| retryable | 같은 요청을 다시 보낼 의미가 있는지 알려 줍니다. 이 값이 최종입니다 — 되돌릴 수 없는 작업(발행·신고·신청)이 접수된 뒤 실패하면 아래 코드별 표와 달리 항상 false 로 옵니다. |
| provider_error_ref | 실패한 지점을 가리키는 추적 값입니다. 보통 상품이름.원인 꼴이고(예: hometax.read_timeout), 없으면 null 입니다. |
| trace_id | 이 요청의 추적 아이디입니다. 서비스문의에 남길 때 그대로 알려 주세요. |
| fields | 선택. HTTP 422 요청 본문 검증 오류에만 있습니다. 어느 필드가 왜 틀렸는지 알려 주는 목록이고 항목마다 loc(위치), msg(이유), type(종류)이 있습니다. 보낸 값은 되돌려 주지 않습니다. |
| reason | 선택. 같은 code 가 여러 상황을 뜻할 때 상황을 가르는 기계용 값입니다. 화면에 보여 주는 값이 아니고, 해당하는 오류에만 있으며 없으면 칸 자체가 없습니다. code 로 먼저 분기하고 더 세분해야 할 때만 보세요. MCP 에서는 도구 호출의 정책 거절이면 result.isError 둘째 블록 JSON 의 reason, 연결을 유지한 tools/list 거절이면 _meta["xdata.kr/refusal"] 의 data.reason, JSON-RPC 오류로 오는 경우는 error.data.reason 에 같은 값이 실립니다. |
reason 값
| 코드 | reason | 언제 |
|---|---|---|
| POLICY_ENV_FORBIDDEN | key_env_not_allowed | 요청한 환경이 이 키에 없습니다. 정식은 요금제를 시작하면, 데모는 사용 신청 승인을 따라 기존 키에 더해지므로 키를 다시 발급하지 않아도 됩니다. |
| POLICY_ENV_FORBIDDEN | demo_access_not_approved | 데모(real_test) 사용 신청이 승인되기 전에 호출했습니다. 콘솔 프로필의 환경 메뉴에서 신청합니다. |
| POLICY_ENV_FORBIDDEN | demo_period_ended | 데모(real_test) 기간이 끝났습니다. 콘솔 결제 관리에서 요금제를 고르면 정식(production) 환경에서 계속 쓸 수 있습니다. |
| POLICY_ENV_FORBIDDEN | organization_required | 데모 환경 요청에는 조직 정보가 필요한데 조직에 속하지 않은 계정으로 호출했습니다. |
| POLICY_QUOTA_EXCEEDED | no_larger_self_serve_plan | 이번 달 사용 토큰을 모두 썼습니다. 다음 달에 다시 채워집니다. 지금 요금제보다 큰 규모가 필요하시면 서비스문의에서 엔터프라이즈 상담을 신청할 수 있습니다. |
| POLICY_QUOTA_EXCEEDED | demo_total_tokens_exhausted | 데모(real_test)에서 조직이 함께 쓰는 체험 총량이 이번 요청에 필요한 만큼 남아 있지 않습니다. 하루 한도와 달리 체험 총량은 월이 바뀌어도 다시 채워지지 않으므로, 콘솔 결제 관리에서 요금제를 고르면 정식(production) 환경에서 계속 쓸 수 있습니다. |
| POLICY_PAID_REQUIRED | production_requires_paid | 요금제를 시작하지 않은 계정이 정식(production) 환경을 호출했습니다. 요금제를 시작하기 전에도 데모 환경은 그대로 쓸 수 있습니다. |
| POLICY_PAID_REQUIRED | subscription_paused | 결제가 일시 중지되어 요청을 처리할 수 없습니다. 콘솔 결제 관리에서 결제 상태를 확인합니다. |
| POLICY_PAID_REQUIRED | invalid_subscription_status | 요금제 상태 때문에 이 요청을 처리할 수 없습니다. 콘솔 결제 관리에서 요금제를 확인해 주세요. 계속되면 서비스문의로 알려 주세요. |
| AUTHZ_FORBIDDEN | oauth_scope_missing | MCP 연결(OAuth)에 도구를 실행할 권한이 없습니다. AI 클라이언트에서 연결을 다시 승인합니다. |
| AUTHZ_FORBIDDEN | oauth_token_mcp_only | AI 앱 연결(MCP)용으로 받은 OAuth 토큰을 서버 연동(REST)에 썼습니다. 다시 승인해도 풀리지 않으며, 서버 연동에는 콘솔에서 발급한 API 키(HTTP Basic)를 씁니다. |
| AUTHZ_FORBIDDEN | credential_takeover_pending | AI 에이전트가 가입시킨 계정의 키인데, 계정을 넘겨받은 사람이 콘솔 키 관리에서 계속 쓰기를 아직 누르지 않았습니다. 키를 폐기하거나 다시 발급할 필요 없이 그 버튼을 누르면 같은 키로 이어서 호출할 수 있습니다. |
| AUTHZ_FORBIDDEN | organization_not_active | 조직이 정지되어 이 요청을 처리할 수 없습니다. 콘솔 결제 관리에서 결제와 계정 상태를 확인하거나 관리자에게 문의해 주세요. |
| POLICY_PROVIDER_FORBIDDEN | available_in_other_env | 이 요금제에 있는 상품인데 요청한 환경에서는 쓸 수 없습니다. 요금제를 바꿀 필요 없이, 메시지가 알려 주는 환경(데모 real_test, 정식 production 중 하나)의 X-Env-Scope 값으로 바꿔 다시 보냅니다. |
| POLICY_PROVIDER_FORBIDDEN | not_sold_yet | 아직 제공하지 않는 기능을 호출했습니다. 어느 요금제에도 아직 없는 기능입니다. 제공 계획은 서비스문의로 문의합니다. |
| POLICY_PROVIDER_FORBIDDEN | sale_ended | 제공이 종료된 기능을 호출했습니다. 팔다가 내린 기능입니다. 대신 쓸 수 있는 기능이 있는지 서비스문의로 문의합니다. |
| POLICY_FEATURE_DISABLED | product_kill_switch_off | 지금은 이용할 수 없는 기능입니다. 요금제나 환경을 바꿔도 풀리지 않으며, 다시 열리는 시점은 서비스문의로 확인합니다. |
| POLICY_FEATURE_DISABLED | runtime_capability_missing | 지금은 이용할 수 없는 기능입니다. 서비스 쪽 준비가 끝나지 않은 기능이라 요금제나 환경을 바꿔도 풀리지 않으며, 다시 열리는 시점은 서비스문의로 확인합니다. |
| RESOURCE_CONFLICT | material_replacement_not_confirmed | 이미 등록된 계정과 같은 아이디인데 비밀번호가 다릅니다. 바꾸려는 것이 맞다면 요청 본문에 confirm 을 true 로 넣어 다시 보냅니다. 그대로 진행하면 저장된 비밀번호가 바뀌고 그 연동으로 열어 둔 기관 세션이 모두 끊어집니다. |
| RESOURCE_CONFLICT | credential_link_in_progress | 같은 자격증명 등록이 아직 처리 중이라 결과를 확인하고 있습니다. 새 Idempotency-Key 로 다시 등록하지 말고, 등록할 때 보낸 키로 GET /v1/credentials/link-operations 를 조회합니다. 200 이면 그 결과를 쓰고, 202 이면 잠시 뒤 다시 조회합니다. 키 없이 등록했다면 콘솔 연동 목록에서 결과를 확인합니다. |
| RESOURCE_CONFLICT | credential_link_commit_outcome_unknown | 자격증명 등록 결과를 저장하는 단계에서 확인 응답을 받지 못해 등록됐는지 아직 알 수 없습니다. 같은 내용을 새 Idempotency-Key 로 다시 등록하지 말고, 등록할 때 보낸 키로 GET /v1/credentials/link-operations 를 조회하거나 콘솔 연동 목록에서 등록됐는지 먼저 확인합니다. |
| RESOURCE_CONFLICT | idempotency_in_progress | 같은 Idempotency-Key 로 앞서 보낸 요청이 아직 처리 중입니다. 응답의 Retry-After 초만큼 기다린 뒤 같은 키와 같은 내용으로 한 번 다시 보냅니다. 그 사이 앞서 보낸 요청이 끝났다면 그 결과가 그대로 돌아옵니다. |
표에 없는 reason 이 오면 무시하고 code 만으로 처리합니다 — 값이 더해질 수 있습니다. 콘솔 화면이 쓰는 값(조직·멤버·초대·환경 신청)은 개발자 API 로 오지 않아 싣지 않았습니다.
reason 이 not_sold_yet 이나 sale_ended 면 요금제를 바꾸거나 추가 구매해도 풀리지 않습니다.살 수 있는 요금제가 없는 기능이라서입니다. 이 문서에 미리 실린 아직 판매하지 않는 기능은 POLICY_PROVIDER_FORBIDDEN 에 not_sold_yet 로, 팔다가 내린 기능은 sale_ended 로 거절됩니다.이 단락은 문서의 설명이고 서버가 보내는 문장이 아닙니다. 서버 문장은 응답의 message 를 그대로 읽습니다.
자주 만나는 오류
| 코드 | HTTP | 재시도 | 할 일 |
|---|---|---|---|
| AUTH_CREDENTIAL_MISSING | 401 | 무의미 | Authorization 헤더를 넣습니다. |
| AUTH_CREDENTIAL_INVALID | 401 | 무의미 | client_id 와 client_secret, Base64 인코딩을 확인하고, 폐기된 키라면 콘솔에서 새 키로 바꿉니다. |
| POLICY_ENV_FORBIDDEN | 403 | 무의미 | X-Env-Scope 값과 키가 쓸 수 있는 환경을 맞춥니다. |
| POLICY_PAID_REQUIRED | 402 | 무의미 | 정식 환경은 현재 공개 요금제를 이용 중일 때만 호출할 수 있습니다. |
| POLICY_QUOTA_EXCEEDED | 429 | 무의미 | 하루 한도는 다음 날 0시(KST)에 다시 채워집니다. 정식 환경의 한 달 한도는 라이트를 포함해 요금제를 시작한 날을 기준으로 한 달 단위로 세며, 다음 주기가 시작되면 다시 채워집니다. 데모 체험 전체 한도는 월이 바뀌어도 충전되지 않습니다. 더 쓰려면 콘솔 결제 관리에서 요금제를 선택합니다. |
| POLICY_RATE_LIMIT_EXCEEDED | 429 | 가능 | 잠시 기다렸다 다시 호출합니다. |
| IDEMPOTENCY_KEY_REQUIRED | 400 | 무의미 | Idempotency-Key 헤더를 넣습니다. |
| IDEMPOTENCY_KEY_CONFLICT | 409 | 무의미 | 같은 요청을 다시 하는 것이면 처음 입력한 내용 그대로, 새 요청이면 새 키로 요청합니다. |
| VALIDATION_INVALID_FIELD | 400, 422 | 무의미 | 본문·헤더 형식과 필드 이름 규칙을 확인합니다. HTTP 422 이면 error.fields 가 틀린 필드를 알려 줍니다. 자격증명이 필요한 작업을 account_link_id 없이 보냈는데 등록한 자격증명이 없을 때도 400 으로 이 코드를 받고, 이때는 작업이 만들어지지 않습니다. 콘솔에서 자격증명을 등록한 뒤 다시 제출합니다. |
| RESOURCE_NOT_FOUND | 404 | 무의미 | 요청에서 가리킨 대상을 찾지 못했습니다. 아이디를 넣었다면 값이 맞고 이 키의 조직과 환경에서 만든 것인지 확인합니다. 작업이 FAILED 로 끝나며 이 코드를 담았다면 그 작업 페이지의 오류 표를 봅니다. 작업 제출에서 account_link_id 가 맞지 않을 때는 이 코드가 아니라 400 VALIDATION_INVALID_FIELD 입니다. |
| JOB_NOT_FOUND | 404 | 무의미 | 작업 아이디와 X-Env-Scope 가 제출할 때와 같은지 확인합니다. |
| JOB_INVALID_TRANSITION | 409 | 무의미 | 작업이 SUCCEEDED 가 된 뒤에 결과를 조회합니다. |
| PROVIDER_AUTH_FAILED | 502 | 무의미 | 등록한 자격증명이 아직 유효한지 확인하고 다시 등록합니다. |
| PROVIDER_SESSION_EXPIRED | 502 | 무의미 | 세션 로그인 작업을 다시 실행한 뒤 이어서 호출합니다. |
| PROVIDER_OUTCOME_UNCONFIRMED | 502 | 무의미 | 다시 보내지 말고 기관 화면에서 처리 여부를 먼저 확인합니다. |
| COMPLIANCE_TOS_VERSION_OUTDATED | 403 | 무의미 | 콘솔 기본정보에서 약관에 다시 동의합니다. |
PROVIDER_OUTCOME_UNCONFIRMED 를 받으면 두 번 처리될 수 있으니 다시 보내기 전에 결과를 먼저 확인합니다.되돌릴 수 없는 작업(발행, 신고, 신청)을 보냈는데 기관이 받았는지 확인하지 못한 상태입니다. 오류 메시지에 확인할 기관 화면이 적혀 있으면 그 화면에서, 없으면 해당 기관 사이트에서 확인합니다.
전체 코드
아래 표는 호출자가 받는 공통 코드입니다. 결제와 운영 화면 전용 코드는 넣지 않았습니다.
인증서 로그인에서 사업자등록번호가 개인사업자 번호일 때도 작업이 POLICY_FEATURE_DISABLED 로 끝납니다.어느 기관 로그인이 그런지와 안내 문장은 그 로그인 액션의 오류 표에 있습니다.
상품을 서비스 쪽에서 일시 중지했을 때는 어느 상품이든 위 reason 표의 POLICY_FEATURE_DISABLED(403)가 옵니다.상품마다 따로 정해 두었던 _DISABLED 코드(예: OPENDATA_DISABLED)는 error.code 로 오지 않으니 분기에는 POLICY_FEATURE_DISABLED 를 쓰세요.다시 보내도, 요청이나 요금제를 바꿔도 풀리지 않으니 서비스문의로 알려 주세요.
재시도 여부는 응답의 retryable 값을 따르세요.표의 재시도 값은 코드 자체의 성격입니다. 되돌릴 수 없는 작업(발행, 신고, 신청)이 접수된 뒤 실패하면 요청이 이미 기관에 닿았을 수 있어, 응답의 retryable 은 그와 상관없이 false 로 옵니다.
서버가 얼마나 기다렸다 다시 보내면 되는지 알면 일부 응답에 Retry-After 응답 헤더(초 단위)가 함께 옵니다.예를 들어 요청이 몰려 서버 연결이 잠시 부족해 SERVICE_UNAVAILABLE(503)로 답할 때입니다. 모든 응답에 오는 값이 아니라 권고 값입니다. 헤더가 없어도 retryable 이 true 면 잠시 뒤 다시 요청해 주세요.
인증·권한
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| AUTH_CREDENTIAL_MISSING | 401 | 무의미 | 인증 헤더 누락 |
| AUTH_CREDENTIAL_INVALID | 401 | 무의미 | client_credential 또는 JWT 위조/만료 |
| AUTH_JWT_EXPIRED | 401 | 무의미 | JWT 만료(콘솔 사용자/관리자) |
| AUTH_REQUIRED | 401 | 무의미 | 기관 세션 재료(쿠키/토큰) 없음 — MCP session login 필요 |
| AUTHZ_FORBIDDEN | 403 | 무의미 | 자원 접근 권한 없음 |
| AUTHZ_ADMIN_ROLE_REQUIRED | 403 | 무의미 | 운영자 역할 필요 |
| SESSION_OWNER_MISMATCH | 403 | 무의미 | 요청한 기관 세션이 이 조직의 것이 아닙니다. 그 세션이 있는지, 누구의 것인지는 알려 주지 않습니다. |
정책·한도
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| POLICY_TIER_FORBIDDEN | 403 | 무의미 | 지금 요금제에서는 쓸 수 없는 요청입니다. |
| POLICY_ENV_FORBIDDEN | 403 | 무의미 | 이 키로 쓸 수 없는 환경(데모, 정식 중 하나)을 호출했습니다. |
| POLICY_PAID_REQUIRED | 402 | 무의미 | 정식 환경을 쓸 수 있는 라이트, 스탠다드, PRO 또는 멀티계정 요금제가 아니거나 결제가 일시 중지된 상태입니다. |
| POLICY_QUOTA_EXCEEDED | 429 | 무의미 | 사용 토큰 한도 초과. 데모는 현재 정책의 기간, 하루 한도와 체험 총량을 적용하고 정식 환경은 현재 요금제의 하루 한도와 한 달 한도를 적용한다. 데모 혜택과 공개 요금제는 GET /v1/public/plans, 계정의 실제 한도와 남은 사용량은 GET /v1/membership/me에서 확인한다. 단위는 회가 아니다. 액션별 사용 토큰은 현재 상품 안내를 따른다 |
| POLICY_RATE_LIMIT_EXCEEDED | 429 | 가능 | 분당 요청 수 한도 초과 |
| POLICY_CONCURRENT_JOBS_EXCEEDED | 429 | 가능 | 같은 기관으로 동시에 진행 중인 작업이 한도에 이르렀습니다. 잠시 뒤 다시 시도하세요. |
| POLICY_PROVIDER_FORBIDDEN | 403 | 무의미 | 요금제/상품에서 허용되지 않는 provider/action |
| POLICY_FEATURE_DISABLED | 403 | 무의미 | Feature Flag 비활성 |
요청 검증
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| RESOURCE_NOT_FOUND | 404 | 무의미 | 자원 미존재 |
| RESOURCE_CONFLICT | 409 | 무의미 | 자원 상태 충돌 |
| RESOURCE_GONE | 410 | 무의미 | 자원이 폐기됨(soft delete 등) |
| VALIDATION_INVALID_FIELD | 400, 422 | 무의미 | 형식이나 타입이 틀렸습니다. 상태가 둘이고 뜻이 다릅니다: 라우트나 도메인 검사에서 걸리면 400, 요청 본문 검증에서 걸리면 422 이고 error.fields 에 필드별 안내가 옵니다. 코드만 보고 분기하지 말고 HTTP 상태도 함께 보세요. |
| VALIDATION_MISSING_FIELD | 400 | 무의미 | 필수 필드 누락 |
| VALIDATION_SEMANTIC_ERROR | 422 | 무의미 | 형식은 맞으나 의미가 잘못됨 |
| VALIDATION_ENV_SCOPE_MISMATCH | 422 | 무의미 | env_scope가 자원/요청 간 불일치 |
| CREDENTIAL_PAYLOAD_UNREADABLE | 400 | 가능 | 연동 저장 때 암호화된 입력을 서버 키로 풀지 못함(오래 열어 둔 화면이 옛 공개키로 암호화 등 - 입력 오류가 아니다). 화면을 새로 고친 뒤 다시 입력하면 풀린다 |
| CREDENTIAL_KEY_UNOPENABLE | 400 | 무의미 | 인증서 연동에 위임장 판(mandate_version)을 함께 보냈을 때 위임장 서명을 위해 인증서 개인키를 열지 못함. 응답 error.reason 이 사유다 - password_suspected(인증서 비밀번호를 확인) · format_unsupported(지원하지 않는 인증서 형식이라 다른 인증서가 필요). 위임장 차단 스위치가 켜진 때만 난다 - 꺼져 있으면 연동은 되고 응답 mandate.failed_reason 에 같은 사유가 실린다 |
| CREDENTIAL_OWNERSHIP_DENIED | 400 | 무의미 | 지정한 연동 계정(account_link_id)을 찾을 수 없거나 이 계정의 것이 아님. 상품 로그인 라우트(400)와 작업 실행 중 확인(FAILED)에서 난다. 콘솔 연동 목록의 계정 ID 를 확인한다. 작업 제출 때의 같은 확인은 VALIDATION_INVALID_FIELD(400)로 거절된다 |
자격증명 한도
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| ACCOUNT_LINK_QUOTA_EXCEEDED | 409 | 무의미 | 통합사(desktop_agent) Plan의 max_active_account_links 시트 한도 초과(용량 충돌 — 시간창 레이트리밋이 아니므로 429 대신 409, SeatLimitPort, AccountLinkService.link) |
멱등성·작업
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| IDEMPOTENCY_KEY_CONFLICT | 409 | 무의미 | 같은 Idempotency-Key로 다른 본문이 들어옴 |
| IDEMPOTENCY_KEY_REQUIRED | 400 | 무의미 | 멱등성 요구 엔드포인트에 키 누락 |
| JOB_INVALID_TRANSITION | 409 | 무의미 | 허용되지 않는 상태 전이 |
| JOB_NOT_FOUND | 404 | 무의미 | 존재하지 않는 job_id |
| JOB_TIMEOUT | 504 | 가능 | 작업 처리 타임아웃(전체 시한 초과) |
| JOB_ACTION_NOT_REGISTERED | 400 | 무의미 | 미등록 (provider, action) 쌍 |
쓰기 확인
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| WRITE_CONFIRMATION_REQUIRED | 400 | 무의미 | 확인 발급물 없이 쓰기를 요청했다. 응답의 error.confirmation_token 에 새 토큰, error.preview 에 미리보기가 실린다 — 그 내용을 고객에게 보여 주고 같은 본문의 params.confirmation_token 에 그 토큰을 넣어 다시 호출한다. MCP 는 result.isError 결과로 오고, 새 토큰은 둘째 블록 JSON 의 confirmation_token, 미리보기는 preview 에 실린다 |
| WRITE_CONFIRMATION_INVALID | 409 | 무의미 | 없음 · 만료(10분) · 이미 소비 · 본문/호출자/plane 불일치. 어느 조건인지 알리지 않는다(오라클 금지). 토큰 없이 다시 호출하면 새 확인을 받는다 |
외부 기관
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| PROVIDER_TIMEOUT_CONNECT | 504 | 가능 | connect 단계 타임아웃 |
| PROVIDER_TIMEOUT_READ | 504 | 가능 | read 단계 타임아웃 |
| PROVIDER_TIMEOUT_OVERALL | 504 | 가능 | 전체 시한 초과 |
| PROVIDER_IP_REJECTED | 502 | 가능 | 기관에서 IP 차단/리젝(403/429/connection_reset/tls_fail) |
| PROVIDER_UNAVAILABLE | 503 | 가능 | 기관 서비스 장애 |
| PROVIDER_BAD_RESPONSE | 502 | 무의미 | 기관 응답이 계약과 불일치 |
| PROVIDER_TLS_VERIFICATION_FAILED | 502 | 무의미 | 기관 연결의 서버 인증서를 검증하지 못함 |
| PROVIDER_AUTH_FAILED | 502 | 무의미 | 기관 자체 인증 실패(자격증명 만료 등) |
| PROVIDER_SESSION_EXPIRED | 502 | 무의미 | 기관 세션 만료(예: NPS Nexacro ErrorCode=-2001, NHIS MainNoXecure HTTP 2xx + 빈 본문) |
| PROVIDER_BUSINESS_ERROR | 200 | 무의미 | 기관 HTTP 200 + 비즈 거부 |
| PROVIDER_VALIDATION_ERROR | 200 | 무의미 | 기관 4xx 검증 거부 |
| PROVIDER_UPSTREAM_ERROR | 200 | 가능 | 기관 5xx 재시도 소진 후 FAILED |
| PROVIDER_OUTCOME_UNCONFIRMED | 502 | 무의미 | 되돌릴 수 없는 기관 쓰기(발행·신고·신청)의 처리 여부를 확인하지 못함. 재시도 금지 — 이미 처리됐을 수 있어 이중 처리가 된다. 메시지에 확인 화면을 싣는다 |
| PROVIDER_PREREQUISITE_REQUIRED | 409 | 무의미 | 고객이 기관 쪽에서 아직 하지 않은 일(가입 · 이용 동의 · 인증서 등록)이 있어 못 한다. 보낸 값은 맞으므로 400 이 아니고, 우리 쪽에서 기다린다고 풀리지 않으므로 재시도도 아니다. 어느 코드가 그것인지와 고객에게 할 말은 상품이 선언한다 |
점검·내부
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| INTERNAL_ERROR | 500 | 무의미 | 분류 불가 내부 오류 |
| INTERNAL_DB_ERROR | 500 | 가능 | DB 처리 실패 |
| INTERNAL_INVARIANT_VIOLATED | 500 | 무의미 | 불변식 위반(트리거/AuthPolicy 방어, severity=CRITICAL) |
| MAINTENANCE_UPSTREAM | 503 | 가능 | 상류 의존 점검 |
| SERVICE_UNAVAILABLE | 503 | 가능 | 우리 쪽 준비가 끝나지 않았다(그 환경의 활성 암호화 키, 또는 파일을 내는 작업의 결과 저장소), 또는 요청이 몰려 DB 연결 풀이 일시적으로 고갈됐다. 작업은 만들어지지 않고 사용량도 차감되지 않는다. 결과 저장소 때문이라면 같은 멱등키로 이미 만든 작업이 있을 때 이 오류 대신 그 작업을 돌려준다 |
약관·컴플라이언스
| 코드 | HTTP | 재시도 | 설명 |
|---|---|---|---|
| COMPLIANCE_TOS_VERSION_OUTDATED | 403 | 무의미 | 필수 약관 미동의 또는 consent_version 불일치 |
| COMPLIANCE_PAYMENT_CONSENT_MISSING | 403 | 무의미 | 결제 도메인 진입 시 결제 관련 약관 미동의 |
| COMPLIANCE_PROVIDER_CONSENT_MISSING | 403 | 무의미 | 그 일을 요청한 사용자를 확인하지 못했거나(작업), 블로그 연결 정보 수집 · 보관 안내에 동의하지 않았다(블로그 연결) |
| COMPLIANCE_DELETION_IN_PROGRESS | 403 | 무의미 | 주체가 진행 중인 삭제 요청에 묶여 호출 차단 |
| COMPLIANCE_INVALID_TRANSITION | 409 | 무의미 | 컴플라이언스 리소스의 비허용 상태 전이 시도 |
| COMPLIANCE_DUPLICATE_REQUEST | 409 | 무의미 | 동일 target에 활성 컴플라이언스 요청 존재 |
| COMPLIANCE_SOLE_OWNER_BLOCK | 409 | 무의미 | 단독 OWNER 사용자 삭제 요청 승인 시도 차단 |
| COMPLIANCE_RETENTION_PURGE_FAILED | 500 | 무의미 | deletion-triggered retention purge 실행 실패 |
| COMPLIANCE_TRANSFER_MANDATE_REQUIRED | 403 | 무의미 | 그 기관 · 인증서의 유효한 전자서명 위임장이 없어 작업 차단 |
작업이 실패했을 때
HTTP 응답이 200 이어도 작업은 실패일 수 있으니 상태를 함께 확인합니다. 작업 처리 흐름을 봅니다.
작업이 FAILED 나 TIMEOUT 으로 끝나면 실패 내용이 상태 응답의 error 에 담깁니다.
- code, message, retryable, provider_error_ref 가 같은 뜻으로 담깁니다.
- trace_id 대신 기관 쪽 HTTP 상태(upstream_status)가 붙습니다.
- next 칸이 늘 있고 아래 두 경우에만 채워집니다. 그 밖에는 null 입니다.
- 블로그 로그인 연결이 끊겨 실패했고 다시 연결할 수 있으면 stage 가 link_credential 이고, 사용자에게 전할 문장(say_to_user)과 연결 창을 여는 주소(action_url)가 담깁니다.
- 은행 거래내역에서 계좌 ID(bank_account_credential_id)를 보내지 않았는데 연동한 계좌가 여러 개라 실패했으면 stage 가 choose_bank_account 이고, 고를 계좌 목록(choices: bank_account_credential_id, 가린 계좌번호 masked_account_no, 기본 계좌 여부 is_default)이 담깁니다.그중 하나의 bank_account_credential_id 를 넣어 같은 요청을 다시 보냅니다.