개발자 문서
개발자 문서

오류 코드

실패한 요청은 error 객체로 답합니다. 코드로 분기하고, 재시도 여부는 응답이 알려 줍니다.

오류 응답에는 error 객체가 있고, code 로 프로그램이 분기합니다.

retryable 이 true 면 같은 요청을 다시 보낼 의미가 있고, false 면 요청이나 설정을 고쳐야 합니다.

사유 칸이 없는 응답 (HTTP 429)

json
{
  "error": {
    "code": "POLICY_QUOTA_EXCEEDED",
    "message": "오늘 사용 가능한 토큰을 모두 사용하였습니다. 매일 0시(한국 시간)에 자동 충전되며, 추가가 필요하시면 콘솔에서 충전하거나 상위 요금제로 변경하실 수 있습니다.",
    "retryable": false,
    "provider_error_ref": null,
    "trace_id": "trc_5f0c2a9e8d7b4c1f9a3e6b2d4c8f1a07"
  }
}

reason 이 붙는 응답 (HTTP 403)

json
{
  "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_FORBIDDENkey_env_not_allowed요청한 환경이 이 키에 없습니다. 정식은 요금제를 시작하면, 데모는 사용 신청 승인을 따라 기존 키에 더해지므로 키를 다시 발급하지 않아도 됩니다.
POLICY_ENV_FORBIDDENdemo_access_not_approved데모(real_test) 사용 신청이 승인되기 전에 호출했습니다. 콘솔 프로필의 환경 메뉴에서 신청합니다.
POLICY_ENV_FORBIDDENdemo_period_ended데모(real_test) 기간이 끝났습니다. 콘솔 결제 관리에서 요금제를 고르면 정식(production) 환경에서 계속 쓸 수 있습니다.
POLICY_ENV_FORBIDDENorganization_required데모 환경 요청에는 조직 정보가 필요한데 조직에 속하지 않은 계정으로 호출했습니다.
POLICY_QUOTA_EXCEEDEDno_larger_self_serve_plan이번 달 사용 토큰을 모두 썼습니다. 다음 달에 다시 채워집니다. 지금 요금제보다 큰 규모가 필요하시면 서비스문의에서 엔터프라이즈 상담을 신청할 수 있습니다.
POLICY_QUOTA_EXCEEDEDdemo_total_tokens_exhausted데모(real_test)에서 조직이 함께 쓰는 체험 총량이 이번 요청에 필요한 만큼 남아 있지 않습니다. 하루 한도와 달리 체험 총량은 월이 바뀌어도 다시 채워지지 않으므로, 콘솔 결제 관리에서 요금제를 고르면 정식(production) 환경에서 계속 쓸 수 있습니다.
POLICY_PAID_REQUIREDproduction_requires_paid요금제를 시작하지 않은 계정이 정식(production) 환경을 호출했습니다. 요금제를 시작하기 전에도 데모 환경은 그대로 쓸 수 있습니다.
POLICY_PAID_REQUIREDsubscription_paused결제가 일시 중지되어 요청을 처리할 수 없습니다. 콘솔 결제 관리에서 결제 상태를 확인합니다.
POLICY_PAID_REQUIREDinvalid_subscription_status요금제 상태 때문에 이 요청을 처리할 수 없습니다. 콘솔 결제 관리에서 요금제를 확인해 주세요. 계속되면 서비스문의로 알려 주세요.
AUTHZ_FORBIDDENoauth_scope_missingMCP 연결(OAuth)에 도구를 실행할 권한이 없습니다. AI 클라이언트에서 연결을 다시 승인합니다.
AUTHZ_FORBIDDENoauth_token_mcp_onlyAI 앱 연결(MCP)용으로 받은 OAuth 토큰을 서버 연동(REST)에 썼습니다. 다시 승인해도 풀리지 않으며, 서버 연동에는 콘솔에서 발급한 API 키(HTTP Basic)를 씁니다.
AUTHZ_FORBIDDENcredential_takeover_pendingAI 에이전트가 가입시킨 계정의 키인데, 계정을 넘겨받은 사람이 콘솔 키 관리에서 계속 쓰기를 아직 누르지 않았습니다. 키를 폐기하거나 다시 발급할 필요 없이 그 버튼을 누르면 같은 키로 이어서 호출할 수 있습니다.
AUTHZ_FORBIDDENorganization_not_active조직이 정지되어 이 요청을 처리할 수 없습니다. 콘솔 결제 관리에서 결제와 계정 상태를 확인하거나 관리자에게 문의해 주세요.
POLICY_PROVIDER_FORBIDDENavailable_in_other_env이 요금제에 있는 상품인데 요청한 환경에서는 쓸 수 없습니다. 요금제를 바꿀 필요 없이, 메시지가 알려 주는 환경(데모 real_test, 정식 production 중 하나)의 X-Env-Scope 값으로 바꿔 다시 보냅니다.
POLICY_PROVIDER_FORBIDDENnot_sold_yet아직 제공하지 않는 기능을 호출했습니다. 어느 요금제에도 아직 없는 기능입니다. 제공 계획은 서비스문의로 문의합니다.
POLICY_PROVIDER_FORBIDDENsale_ended제공이 종료된 기능을 호출했습니다. 팔다가 내린 기능입니다. 대신 쓸 수 있는 기능이 있는지 서비스문의로 문의합니다.
POLICY_FEATURE_DISABLEDproduct_kill_switch_off지금은 이용할 수 없는 기능입니다. 요금제나 환경을 바꿔도 풀리지 않으며, 다시 열리는 시점은 서비스문의로 확인합니다.
POLICY_FEATURE_DISABLEDruntime_capability_missing지금은 이용할 수 없는 기능입니다. 서비스 쪽 준비가 끝나지 않은 기능이라 요금제나 환경을 바꿔도 풀리지 않으며, 다시 열리는 시점은 서비스문의로 확인합니다.
RESOURCE_CONFLICTmaterial_replacement_not_confirmed이미 등록된 계정과 같은 아이디인데 비밀번호가 다릅니다. 바꾸려는 것이 맞다면 요청 본문에 confirm 을 true 로 넣어 다시 보냅니다. 그대로 진행하면 저장된 비밀번호가 바뀌고 그 연동으로 열어 둔 기관 세션이 모두 끊어집니다.
RESOURCE_CONFLICTcredential_link_in_progress같은 자격증명 등록이 아직 처리 중이라 결과를 확인하고 있습니다. 새 Idempotency-Key 로 다시 등록하지 말고, 등록할 때 보낸 키로 GET /v1/credentials/link-operations 를 조회합니다. 200 이면 그 결과를 쓰고, 202 이면 잠시 뒤 다시 조회합니다. 키 없이 등록했다면 콘솔 연동 목록에서 결과를 확인합니다.
RESOURCE_CONFLICTcredential_link_commit_outcome_unknown자격증명 등록 결과를 저장하는 단계에서 확인 응답을 받지 못해 등록됐는지 아직 알 수 없습니다. 같은 내용을 새 Idempotency-Key 로 다시 등록하지 말고, 등록할 때 보낸 키로 GET /v1/credentials/link-operations 를 조회하거나 콘솔 연동 목록에서 등록됐는지 먼저 확인합니다.
RESOURCE_CONFLICTidempotency_in_progress같은 Idempotency-Key 로 앞서 보낸 요청이 아직 처리 중입니다. 응답의 Retry-After 초만큼 기다린 뒤 같은 키와 같은 내용으로 한 번 다시 보냅니다. 그 사이 앞서 보낸 요청이 끝났다면 그 결과가 그대로 돌아옵니다.

표에 없는 reason 이 오면 무시하고 code 만으로 처리합니다 — 값이 더해질 수 있습니다. 콘솔 화면이 쓰는 값(조직·멤버·초대·환경 신청)은 개발자 API 로 오지 않아 싣지 않았습니다.

reason 이 not_sold_yet 이나 sale_ended 면 요금제를 바꾸거나 추가 구매해도 풀리지 않습니다.

자주 만나는 오류

코드HTTP재시도할 일
AUTH_CREDENTIAL_MISSING401무의미Authorization 헤더를 넣습니다.
AUTH_CREDENTIAL_INVALID401무의미client_id 와 client_secret, Base64 인코딩을 확인하고, 폐기된 키라면 콘솔에서 새 키로 바꿉니다.
POLICY_ENV_FORBIDDEN403무의미X-Env-Scope 값과 키가 쓸 수 있는 환경을 맞춥니다.
POLICY_PAID_REQUIRED402무의미정식 환경은 현재 공개 요금제를 이용 중일 때만 호출할 수 있습니다.
POLICY_QUOTA_EXCEEDED429무의미하루 한도는 다음 날 0시(KST)에 다시 채워집니다. 정식 환경의 한 달 한도는 라이트를 포함해 요금제를 시작한 날을 기준으로 한 달 단위로 세며, 다음 주기가 시작되면 다시 채워집니다. 데모 체험 전체 한도는 월이 바뀌어도 충전되지 않습니다. 더 쓰려면 콘솔 결제 관리에서 요금제를 선택합니다.
POLICY_RATE_LIMIT_EXCEEDED429가능잠시 기다렸다 다시 호출합니다.
IDEMPOTENCY_KEY_REQUIRED400무의미Idempotency-Key 헤더를 넣습니다.
IDEMPOTENCY_KEY_CONFLICT409무의미같은 요청을 다시 하는 것이면 처음 입력한 내용 그대로, 새 요청이면 새 키로 요청합니다.
VALIDATION_INVALID_FIELD400, 422무의미본문·헤더 형식과 필드 이름 규칙을 확인합니다. HTTP 422 이면 error.fields 가 틀린 필드를 알려 줍니다. 자격증명이 필요한 작업을 account_link_id 없이 보냈는데 등록한 자격증명이 없을 때도 400 으로 이 코드를 받고, 이때는 작업이 만들어지지 않습니다. 콘솔에서 자격증명을 등록한 뒤 다시 제출합니다.
RESOURCE_NOT_FOUND404무의미요청에서 가리킨 대상을 찾지 못했습니다. 아이디를 넣었다면 값이 맞고 이 키의 조직과 환경에서 만든 것인지 확인합니다. 작업이 FAILED 로 끝나며 이 코드를 담았다면 그 작업 페이지의 오류 표를 봅니다. 작업 제출에서 account_link_id 가 맞지 않을 때는 이 코드가 아니라 400 VALIDATION_INVALID_FIELD 입니다.
JOB_NOT_FOUND404무의미작업 아이디와 X-Env-Scope 가 제출할 때와 같은지 확인합니다.
JOB_INVALID_TRANSITION409무의미작업이 SUCCEEDED 가 된 뒤에 결과를 조회합니다.
PROVIDER_AUTH_FAILED502무의미등록한 자격증명이 아직 유효한지 확인하고 다시 등록합니다.
PROVIDER_SESSION_EXPIRED502무의미세션 로그인 작업을 다시 실행한 뒤 이어서 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED502무의미다시 보내지 말고 기관 화면에서 처리 여부를 먼저 확인합니다.
COMPLIANCE_TOS_VERSION_OUTDATED403무의미콘솔 기본정보에서 약관에 다시 동의합니다.

PROVIDER_OUTCOME_UNCONFIRMED 를 받으면 두 번 처리될 수 있으니 다시 보내기 전에 결과를 먼저 확인합니다.

전체 코드

아래 표는 호출자가 받는 공통 코드입니다. 결제와 운영 화면 전용 코드는 넣지 않았습니다.

인증서 로그인에서 사업자등록번호가 개인사업자 번호일 때도 작업이 POLICY_FEATURE_DISABLED 로 끝납니다.

상품을 서비스 쪽에서 일시 중지했을 때는 어느 상품이든 위 reason 표의 POLICY_FEATURE_DISABLED(403)가 옵니다.

재시도 여부는 응답의 retryable 값을 따르세요.

서버가 얼마나 기다렸다 다시 보내면 되는지 알면 일부 응답에 Retry-After 응답 헤더(초 단위)가 함께 옵니다.

인증·권한

코드HTTP재시도설명
AUTH_CREDENTIAL_MISSING401무의미인증 헤더 누락
AUTH_CREDENTIAL_INVALID401무의미client_credential 또는 JWT 위조/만료
AUTH_JWT_EXPIRED401무의미JWT 만료(콘솔 사용자/관리자)
AUTH_REQUIRED401무의미기관 세션 재료(쿠키/토큰) 없음 — MCP session login 필요
AUTHZ_FORBIDDEN403무의미자원 접근 권한 없음
AUTHZ_ADMIN_ROLE_REQUIRED403무의미운영자 역할 필요
SESSION_OWNER_MISMATCH403무의미요청한 기관 세션이 이 조직의 것이 아닙니다. 그 세션이 있는지, 누구의 것인지는 알려 주지 않습니다.

정책·한도

코드HTTP재시도설명
POLICY_TIER_FORBIDDEN403무의미지금 요금제에서는 쓸 수 없는 요청입니다.
POLICY_ENV_FORBIDDEN403무의미이 키로 쓸 수 없는 환경(데모, 정식 중 하나)을 호출했습니다.
POLICY_PAID_REQUIRED402무의미정식 환경을 쓸 수 있는 라이트, 스탠다드, PRO 또는 멀티계정 요금제가 아니거나 결제가 일시 중지된 상태입니다.
POLICY_QUOTA_EXCEEDED429무의미사용 토큰 한도 초과. 데모는 현재 정책의 기간, 하루 한도와 체험 총량을 적용하고 정식 환경은 현재 요금제의 하루 한도와 한 달 한도를 적용한다. 데모 혜택과 공개 요금제는 GET /v1/public/plans, 계정의 실제 한도와 남은 사용량은 GET /v1/membership/me에서 확인한다. 단위는 회가 아니다. 액션별 사용 토큰은 현재 상품 안내를 따른다
POLICY_RATE_LIMIT_EXCEEDED429가능분당 요청 수 한도 초과
POLICY_CONCURRENT_JOBS_EXCEEDED429가능같은 기관으로 동시에 진행 중인 작업이 한도에 이르렀습니다. 잠시 뒤 다시 시도하세요.
POLICY_PROVIDER_FORBIDDEN403무의미요금제/상품에서 허용되지 않는 provider/action
POLICY_FEATURE_DISABLED403무의미Feature Flag 비활성

요청 검증

코드HTTP재시도설명
RESOURCE_NOT_FOUND404무의미자원 미존재
RESOURCE_CONFLICT409무의미자원 상태 충돌
RESOURCE_GONE410무의미자원이 폐기됨(soft delete 등)
VALIDATION_INVALID_FIELD400, 422무의미형식이나 타입이 틀렸습니다. 상태가 둘이고 뜻이 다릅니다: 라우트나 도메인 검사에서 걸리면 400, 요청 본문 검증에서 걸리면 422 이고 error.fields 에 필드별 안내가 옵니다. 코드만 보고 분기하지 말고 HTTP 상태도 함께 보세요.
VALIDATION_MISSING_FIELD400무의미필수 필드 누락
VALIDATION_SEMANTIC_ERROR422무의미형식은 맞으나 의미가 잘못됨
VALIDATION_ENV_SCOPE_MISMATCH422무의미env_scope가 자원/요청 간 불일치
CREDENTIAL_PAYLOAD_UNREADABLE400가능연동 저장 때 암호화된 입력을 서버 키로 풀지 못함(오래 열어 둔 화면이 옛 공개키로 암호화 등 - 입력 오류가 아니다). 화면을 새로 고친 뒤 다시 입력하면 풀린다
CREDENTIAL_KEY_UNOPENABLE400무의미인증서 연동에 위임장 판(mandate_version)을 함께 보냈을 때 위임장 서명을 위해 인증서 개인키를 열지 못함. 응답 error.reason 이 사유다 - password_suspected(인증서 비밀번호를 확인) · format_unsupported(지원하지 않는 인증서 형식이라 다른 인증서가 필요). 위임장 차단 스위치가 켜진 때만 난다 - 꺼져 있으면 연동은 되고 응답 mandate.failed_reason 에 같은 사유가 실린다
CREDENTIAL_OWNERSHIP_DENIED400무의미지정한 연동 계정(account_link_id)을 찾을 수 없거나 이 계정의 것이 아님. 상품 로그인 라우트(400)와 작업 실행 중 확인(FAILED)에서 난다. 콘솔 연동 목록의 계정 ID 를 확인한다. 작업 제출 때의 같은 확인은 VALIDATION_INVALID_FIELD(400)로 거절된다

자격증명 한도

코드HTTP재시도설명
ACCOUNT_LINK_QUOTA_EXCEEDED409무의미통합사(desktop_agent) Plan의 max_active_account_links 시트 한도 초과(용량 충돌 — 시간창 레이트리밋이 아니므로 429 대신 409, SeatLimitPort, AccountLinkService.link)

멱등성·작업

코드HTTP재시도설명
IDEMPOTENCY_KEY_CONFLICT409무의미같은 Idempotency-Key로 다른 본문이 들어옴
IDEMPOTENCY_KEY_REQUIRED400무의미멱등성 요구 엔드포인트에 키 누락
JOB_INVALID_TRANSITION409무의미허용되지 않는 상태 전이
JOB_NOT_FOUND404무의미존재하지 않는 job_id
JOB_TIMEOUT504가능작업 처리 타임아웃(전체 시한 초과)
JOB_ACTION_NOT_REGISTERED400무의미미등록 (provider, action) 쌍

쓰기 확인

코드HTTP재시도설명
WRITE_CONFIRMATION_REQUIRED400무의미확인 발급물 없이 쓰기를 요청했다. 응답의 error.confirmation_token 에 새 토큰, error.preview 에 미리보기가 실린다 — 그 내용을 고객에게 보여 주고 같은 본문의 params.confirmation_token 에 그 토큰을 넣어 다시 호출한다. MCP 는 result.isError 결과로 오고, 새 토큰은 둘째 블록 JSON 의 confirmation_token, 미리보기는 preview 에 실린다
WRITE_CONFIRMATION_INVALID409무의미없음 · 만료(10분) · 이미 소비 · 본문/호출자/plane 불일치. 어느 조건인지 알리지 않는다(오라클 금지). 토큰 없이 다시 호출하면 새 확인을 받는다

외부 기관

코드HTTP재시도설명
PROVIDER_TIMEOUT_CONNECT504가능connect 단계 타임아웃
PROVIDER_TIMEOUT_READ504가능read 단계 타임아웃
PROVIDER_TIMEOUT_OVERALL504가능전체 시한 초과
PROVIDER_IP_REJECTED502가능기관에서 IP 차단/리젝(403/429/connection_reset/tls_fail)
PROVIDER_UNAVAILABLE503가능기관 서비스 장애
PROVIDER_BAD_RESPONSE502무의미기관 응답이 계약과 불일치
PROVIDER_TLS_VERIFICATION_FAILED502무의미기관 연결의 서버 인증서를 검증하지 못함
PROVIDER_AUTH_FAILED502무의미기관 자체 인증 실패(자격증명 만료 등)
PROVIDER_SESSION_EXPIRED502무의미기관 세션 만료(예: NPS Nexacro ErrorCode=-2001, NHIS MainNoXecure HTTP 2xx + 빈 본문)
PROVIDER_BUSINESS_ERROR200무의미기관 HTTP 200 + 비즈 거부
PROVIDER_VALIDATION_ERROR200무의미기관 4xx 검증 거부
PROVIDER_UPSTREAM_ERROR200가능기관 5xx 재시도 소진 후 FAILED
PROVIDER_OUTCOME_UNCONFIRMED502무의미되돌릴 수 없는 기관 쓰기(발행·신고·신청)의 처리 여부를 확인하지 못함. 재시도 금지 — 이미 처리됐을 수 있어 이중 처리가 된다. 메시지에 확인 화면을 싣는다
PROVIDER_PREREQUISITE_REQUIRED409무의미고객이 기관 쪽에서 아직 하지 않은 일(가입 · 이용 동의 · 인증서 등록)이 있어 못 한다. 보낸 값은 맞으므로 400 이 아니고, 우리 쪽에서 기다린다고 풀리지 않으므로 재시도도 아니다. 어느 코드가 그것인지와 고객에게 할 말은 상품이 선언한다

점검·내부

코드HTTP재시도설명
INTERNAL_ERROR500무의미분류 불가 내부 오류
INTERNAL_DB_ERROR500가능DB 처리 실패
INTERNAL_INVARIANT_VIOLATED500무의미불변식 위반(트리거/AuthPolicy 방어, severity=CRITICAL)
MAINTENANCE_UPSTREAM503가능상류 의존 점검
SERVICE_UNAVAILABLE503가능우리 쪽 준비가 끝나지 않았다(그 환경의 활성 암호화 키, 또는 파일을 내는 작업의 결과 저장소), 또는 요청이 몰려 DB 연결 풀이 일시적으로 고갈됐다. 작업은 만들어지지 않고 사용량도 차감되지 않는다. 결과 저장소 때문이라면 같은 멱등키로 이미 만든 작업이 있을 때 이 오류 대신 그 작업을 돌려준다

약관·컴플라이언스

코드HTTP재시도설명
COMPLIANCE_TOS_VERSION_OUTDATED403무의미필수 약관 미동의 또는 consent_version 불일치
COMPLIANCE_PAYMENT_CONSENT_MISSING403무의미결제 도메인 진입 시 결제 관련 약관 미동의
COMPLIANCE_PROVIDER_CONSENT_MISSING403무의미그 일을 요청한 사용자를 확인하지 못했거나(작업), 블로그 연결 정보 수집 · 보관 안내에 동의하지 않았다(블로그 연결)
COMPLIANCE_DELETION_IN_PROGRESS403무의미주체가 진행 중인 삭제 요청에 묶여 호출 차단
COMPLIANCE_INVALID_TRANSITION409무의미컴플라이언스 리소스의 비허용 상태 전이 시도
COMPLIANCE_DUPLICATE_REQUEST409무의미동일 target에 활성 컴플라이언스 요청 존재
COMPLIANCE_SOLE_OWNER_BLOCK409무의미단독 OWNER 사용자 삭제 요청 승인 시도 차단
COMPLIANCE_RETENTION_PURGE_FAILED500무의미deletion-triggered retention purge 실행 실패
COMPLIANCE_TRANSFER_MANDATE_REQUIRED403무의미그 기관 · 인증서의 유효한 전자서명 위임장이 없어 작업 차단

작업이 실패했을 때

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)이 담깁니다.