멀티계정 오류와 운영
실패, 응답 유실, 키 교체를 구분하고 같은 요청을 복구합니다.
SDK는 읽기와 쓰기 모두 자동 HTTP 재시도를 하지 않습니다. 아래 기준으로 고객사 호출자가 판단합니다.
빠른 시작, 개발 규격, 사용자 업무 실행 UI 예시를 먼저 보세요.
정상 플로우 체크리스트
- 키·환경 확인
멀티계정 키의 env_scope와 콘솔 키 관리의 허용 환경이 일치하고 catalog 조회가 성공합니다.
- 기관 준비물
연결 전 기관별 준비물에서 provider별 재료·VID·계좌 입력을 확인합니다.
- 고객 연결
operation_id 저장 → link → account_link_id를 고객·기관·환경과 매핑 → probe로 ACTIVE 확인합니다.
- 작업 실행
업무 요청 키 저장 → account_link_id 지정 → job_id 저장 → SUCCEEDED 후 결과를 업무 DB에 한 번만 반영합니다.같은 키에 같은 본문으로 다시 보내면 새 작업을 만들지 않고 이미 접수된 작업을 그대로 돌려줍니다(HTTP 200).
- 막히면
아래 오류 표와 등록·작업 복구 절을 따르고, 새 ID를 만들기 전에 원래 요청의 접수 여부를 확인합니다.
1. 오류별 다음 행동
| 코드 / 증상 | 다음 행동 |
|---|---|
| INVALID_BASE_URL | 빠른 시작의 API 주소를 복사하세요. 콘솔 주소·/v1·쿼리를 붙이지 않습니다. |
| HTTPS_REQUIRED | 고객용 API는 HTTPS 주소를 사용합니다. |
| INVALID_ENVIRONMENT | env_scope가 SDK가 아는 환경 이름이 아닙니다(SDK가 HTTP 호출 전에 확인). 데모는 real_test, 정식은 production입니다. |
| 403 | 먼저 콘솔 키 관리에서 이 키의 허용 환경을 확인합니다(데모=real_test). 다음으로 오류 code에 따라 기본정보의 약관 동의 또는 상품 이용 권한을 확인합니다. |
| 401 AUTH_CREDENTIAL_INVALID | 키 조합과 폐기 상태 확인. secret 재조회 대신 재발급. SDK가 client_id·client_secret 형식을 보고 내는 INVALID_CLIENT_CREDENTIAL은 HTTP 호출 전에 나는 별개 오류입니다 |
| INVALID_OPERATION_ID | SDK new_operation_id()로 만든 원래 등록 ID 사용. 업무 요청 키와 혼동 금지 |
| INVALID_IDEMPOTENCY_KEY | 작업 키는 공백 없는 ASCII 1~128자. 같은 업무는 기존 키 유지 |
| 409 IDEMPOTENCY_KEY_CONFLICT | 같은 요청 키를 내용이 다른 요청에 썼습니다. 먼저 원래 요청의 본문이 실수로 바뀌었는지 확인합니다. 같은 업무의 재전송이면 원래 본문과 키를 그대로 보내고, 별도의 새 업무로 확정한 경우에만 새 키를 만듭니다. 재시도 계약 참고. 등록 요청은 처음 보낸 지 24시간이 지난 operation_id를 다시 보낼 때도 같은 코드입니다(SDK 오류에는 문장이 담기지 않으므로 보낸 시각으로 구분) — 연동 상태를 먼저 확인한 뒤 필요하면 새 operation_id로 다시 요청합니다 |
| 409 RESOURCE_CONFLICT (연결 등록 호출 시, 먼저 등록 결과 확인) | 같은 operation_id 의 등록이 아직 처리 중이거나, 등록 결과를 저장하는 단계의 확인 응답을 받지 못했을 때도 연결 등록 호출이 409 RESOURCE_CONFLICT 를 받습니다(원문 HTTP 응답의 error.reason 은 credential_link_in_progress 또는 credential_link_commit_outcome_unknown). SDK 오류에는 reason 이 담기지 않으므로, link 로 시작하는 등록 호출이 409 RESOURCE_CONFLICT 를 받으면 새 operation_id 로 다시 등록하지 말고 먼저 같은 operation_id 로 등록 결과를 조회합니다(Python get_link_operation, .NET GetLinkOperationAsync, 아래 2단계). COMPLETED 면 그 결과의 account_link_id 를 쓰고, UNKNOWN 이면 잠시 뒤 다시 조회합니다. 둘 다 아니고 link_id_password 나 LinkIdPasswordAsync 를 불렀다면 아래 행의 확인 요구입니다 |
| 409 RESOURCE_CONFLICT (link_id_password, LinkIdPasswordAsync 호출 시) | 기관 아이디와 비밀번호 연결을 같은 아이디에 다른 비밀번호로 다시 등록하면서 confirm을 켜지 않았을 때입니다. 옛 비밀번호로 되돌릴 수 없고 그 연결로 열어 둔 기관 세션이 모두 끊기므로 서버가 바꾸려는 것이 맞다는 명시 확인을 요구합니다. 0.1.2 SDK의 link_id_password와 LinkIdPasswordAsync는 confirm 인자를 받습니다(기본은 꺼짐) — 고객의 새 비밀번호를 확인했으면 같은 operation_id로 confirm=True(파이썬) 또는 confirm: true(닷넷)를 실어 같은 호출을 다시 합니다. XbossError(파이썬)는 code·http_status·outcome_unknown·request_id·trace_id·retry_after를, XbossException(닷넷)은 Code·Status·OutcomeUnknown·RequestId·TraceId·RetryAfter만 담고 원문 error.reason은 전달하지 않으므로, 이 409는 reason 문자열이 아니라 link_id_password나 LinkIdPasswordAsync를 불렀다는 사실과 위 행의 등록 결과 조회로 구분하세요(원문 HTTP 응답의 error.reason은 개발 규격 8절의 HTTP 방식으로 직접 호출할 때만 보입니다). 인증서 기관은 이 오류가 나지 않습니다. 0.1.2 SDK 는 사업자번호를 보내지 않으므로 일련번호가 다른 인증서는 대개 새 연결(201)이고, 같은 기관에 주체와 발급기관이 같은 인증서 연결이 콘솔에서 등록된 것 하나뿐이면 그 연결을 새 인증서로 바꿉니다(200, outcome UPDATED, 같은 account_link_id). 멀티계정 키로 등록하거나 다시 등록한 적이 있는 연결은 이렇게 바뀌지 않습니다. HTTP 로 사업자번호(biz_number)를 함께 보냈고 같은 기관에 사업자번호가 같은 인증서가 이미 있으면 그 연결을 새 인증서로 바꾸되(200, outcome UPDATED), 옛 인증서와 인증서에 적힌 이름(요청의 cert_name 이 아니라 인증서 자체의 이름)이 다르면 바꾸지 않고 400 VALIDATION_INVALID_FIELD 입니다. 이렇게 바꾸는 두 경우 모두 새 인증서의 유효기간이 지났으면 바꾸지 않고 400 입니다. 자세한 규칙은 자격증명 연동의 다시 등록 표에 있습니다 |
| 409 ACCOUNT_LINK_QUOTA_EXCEEDED | 요금제의 연결 수 한도(활성 연결 수)를 모두 써서 연결을 더 만들 수 없습니다. 429가 아니라 409이고, 기다려도 풀리지 않습니다. 쓰지 않는 연결을 해제하거나 콘솔 결제 화면에서 요금제를 확인합니다. SDK 0.1.2는 이 값을 code에 그대로 담습니다 — 오류 코드 |
| HTTP_ERROR | SDK가 응답의 code를 공개 오류 코드 목록에서 알아보지 못했을 때 붙이는 대체값입니다. SDK가 나온 뒤에 새로 생긴 코드이거나 JSON이 아닌 응답일 때입니다. http_status·request_id·trace_id를 보존하고 브라우저에 secret·인증서 원문을 노출하지 않음 — 오류 코드 |
| 400 VALIDATION_INVALID_FIELD (해제 사유 거부) | unlink_reason은 user_request / admin_action / security_incident 중 하나를 씁니다. 인증서 연결에 그 밖의 문자열(예: e2e_relink)을 보내면 400입니다. 고객사 UI·운영 스크립트 enum을 맞춤 |
| UNSUPPORTED_CREDENTIAL_KIND / CONTRACT / INVALID_CREDENTIAL_INPUT | 실제 기관 목록과 input_contract 확인. 임의 형식으로 우회하지 않음 |
| 503 SERVICE_UNAVAILABLE (연결 등록 호출 시) | 같은 계정의 다른 연결 처리가 진행 중이어서 이번 등록은 아무것도 바꾸지 않았습니다. SDK 는 5xx 이므로 outcome_unknown 을 true 로 담지만, 이 코드는 새 operation_id 를 만들지 말고 retry_after(닷넷 RetryAfter) 초만큼 기다린 뒤 같은 operation_id 와 같은 본문으로 다시 등록합니다. |
| TRANSPORT_ERROR / INVALID_RESPONSE / 5xx | 오류의 outcome_unknown이 true이면 접수 여부가 불명확합니다. 새 ID를 만들지 말고 아래 2단계 등록 복구 또는 3단계 작업 복구를 따릅니다. |
| 429 | 토큰 한도(POLICY_QUOTA_EXCEEDED), 호출 속도(POLICY_RATE_LIMIT_EXCEEDED), 동시 작업 제한(POLICY_CONCURRENT_JOBS_EXCEEDED)을 code로 구분합니다. 토큰 한도는 해당 한도의 초기화와 요금제 조건을 확인하고, 호출 속도 제한은 잠시 기다립니다. 같은 업무의 재시도에는 저장한 요청 키와 동일한 본문을 유지합니다. |
| 429 POLICY_CONCURRENT_JOBS_EXCEEDED | 같은 고객사와 기관에 접수돼 대기 중이거나 실행 중인 작업이 동시 작업 한도에 도달했습니다. 최종 고객의 account_link_id가 달라도 같은 고객사와 기관의 한도를 함께 사용할 수 있습니다. 이미 받은 job_id의 진행 상태를 확인하고, 작업이 끝난 뒤 접수되지 않은 업무를 저장한 요청 키와 동일한 본문으로 다시 보냅니다. 이미 접수된 작업을 새 키로 중복 제출하지 않습니다. 고정된 동시 작업 수나 대기 시간을 가정하지 마세요. 접수 여부가 불명확하면 아래 작업 복구 절을 먼저 따릅니다. |
| 로컬 FileExistsError (recover_connection.py prepare 를 쓴 경우) | 기존 journal 확인. 파일 삭제로 새 요청을 만들지 않음 |
VID(random_enc)가 인증서와 짝이 맞지 않을 때
연결은 됐는데 로그인 작업이 실패하고 원인이 random_enc(VID)와 인증서의 짝 불일치라면 동일 cert bytes로 VID를 다시 획득하고, 해제 후 새 operation_id로 재연결하세요.기관별 준비물의 VID 경로를 참고하세요.
원인 가운데 하나는 random_enc(VID)가 link에 넣은 인증서 bytes와 짝이 맞지 않는 경우입니다.서버가 개인키에서 값을 읽었다면 보낸 값과 달라도 서버가 읽은 값을 쓰므로 이 문제는 생기지 않습니다. 서버가 읽지 못해 보낸 값을 쓴 경우에는 그 값이 이 인증서의 것인지 확인하지 못해, 짝이 맞지 않아도 연결은 만들어집니다.
화면에서 고른 인증서, VID를 뽑은 인증서, DB에서 읽은 cert bytes가 다르면 같은 문제가 생길 수 있습니다.XBOSS 연결 프로그램(코드의 이름은 PKI Agent), 고객사 인증 모듈 등 경로와 무관하고, 이름이나 발급자만 보고 자동 매칭한 경우도 포함됩니다.
재연결 응답의 account_link_id는 새 값이라고 가정하지 말고 그대로 저장하세요.해제한 연결과 같은 인증서로 다시 연결하면 서버가 이전 account_link_id를 그대로 돌려줄 수 있습니다.
멱등 재연결(IDEMPOTENT_MATCH)과 stale VID
예전 VID가 남아 로그인 작업만 실패하면 probe 성공만으로 연결을 유지하지 말고, unlink 후 새 operation_id로 재연결하세요. 화면에 「이미 연결됨」이 나와도 같습니다.
같은 provider와 인증서로 link를 다시 호출하면 XBOSS가 기존 account_link_id를 반환할 수 있습니다.서버가 이번 요청의 개인키에서 값을 읽었다면 저장된 VID를 그 값으로 바로잡습니다. 서버가 읽지 못하고 보낸 random_enc만 있으면 저장값은 바뀌지 않으므로 이 응답은 새 random_enc로 VID를 갱신하지 않습니다.
| 증상 | 원인 후보 | 다음 행동 |
|---|---|---|
| link 성공·같은 account_link_id | 멱등 매칭으로 기존 연결 재사용(outcome IDEMPOTENT_MATCH), 또는 기존 연결을 새 인증서로 바꿈(outcome UPDATED) | 로그인 작업 성공 여부로 판단. 실패 시 unlink·재연결 |
| 로그인만 VID 불일치 | 서버가 읽지 못해 보낸 stale random_enc를 썼거나 cert bytes 불일치 | 같은 인증서로 link를 다시 호출(서버가 개인키에서 읽으면 저장값이 바로잡힙니다) → 서버가 읽지 못하는 키면 동일 cert bytes로 VID 재획득 → unlink → 새 operation_id → link |
| unlink 거부(진행 중 작업) | 해당 account_link_id로 작업이 QUEUED 또는 RUNNING이거나, 기관 결과를 확인하지 못한 채 끝난 작업이 있어 운영 확인을 기다리는 중 | 작업 완료·실패 확인 후 해제. 작업이 모두 끝났는데도 거부되면 잠시 뒤 다시 시도하고, 계속되면 그 연결의 마지막 job_id 로 문의 |
2. 등록 요청 복구
등록 전 저장한 operation_id를 24시간 복구 범위 안에서 조회하고, 접수 여부가 확인될 때까지 새 연결 요청을 보내지 않습니다.
- COMPLETED는 과거 결과이니 probe로 현재 상태를 확인해야 합니다.
- UNKNOWN, 404는 미실행 증거가 아닙니다. 서버, 환경, 키 소유자(등록할 때 쓴 키의 소유자), 원래 ID를 대조하세요.
- 계속 불명확하거나 만료됐다면 아래 5단계의 문의 정보로 XBOSS에 접수 여부를 확인하세요. 키와 입력 원문은 보내지 않습니다.
- 24시간을 넘긴 기록이 남아 있어도 재실행이 허용된다는 뜻은 아닙니다.
# ZIP을 푼 폴더. 새 창에서도 필요한 값들을 모두 지정합니다.
$apiBase = Read-Host '원래 API origin'
$clientId = Read-Host '등록할 때 쓴 키와 소유자가 같은 현재 유효한 client_id(재발급 키 포함)'
$environment = Read-Host '원래 환경: real_test / production'
if ($environment -notin @('real_test', 'production')) { throw '원래 환경을 확인하세요.' }
$operationId = Read-Host '등록 전에 고객사 DB에 저장한 operation_id'
$argsForRecovery = @(
'recover',
'--base-url', $apiBase, '--env', $environment,
'--client-id', $clientId,
'--operation-id', $operationId
)
./.venv/Scripts/python.exe ./python/examples/connect.py @argsForRecovery결과 읽기: client secret은 숨김 입력으로 받습니다.state: COMPLETED 이면 이어서 account_link_id: 가 출력되고, 그 밖의 상태면 상태만 출력하고 종료 코드 2로 끝납니다.
고객사 백엔드에서는 같은 조회를 Python client.get_link_operation(operation_id), .NET GetLinkOperationAsync 로 합니다.
예제 ZIP의 recover_connection.py 는 그 스크립트의 prepare 로 연결 journal 파일을 먼저 만든 경우에만 씁니다.
3. 작업 복구는 등록 복구와 다릅니다
- job_id가 있으면 상태와 결과를 조회합니다.
- 응답을 잃어 job_id가 없다면 고객사 구현은 같은 조직, 원래 환경에서 원래 Idempotency-Key(request_key)와 동일 요청 본문을 씁니다.
- 화면 「진행 상태 확인」은 이 복구가 아니라 저장된 job_id로 GET만 하는 재조회입니다.
- 사용자 「다시 실행」은 새 request_reference와 새 request_key로 새 작업입니다(개발 규격 §7 재조회, 복구, 새 실행).
- 409이면 본문과 키 충돌을 확인하고 새 키로 자동 우회하지 않습니다.
- 기존 작업의 보존과 조회 가능 여부가 불명확하면 먼저 XBOSS에 확인합니다.
- 기간 경과나 인증 문맥 변경 때는 운영 확인이 필요합니다.
재시도 계약을 참고하세요.
| 상태 | 고객사 처리 |
|---|---|
| QUEUED / RUNNING | 같은 작업 조회. 조회 횟수·간격·전체 대기 한도를 명시 |
| SUCCEEDED | 결과 조회 후 기존 업무 DB에 한 번만 반영 |
| FAILED / CANCELED / TIMEOUT | 오류와 업무 영향 확인. 자동 신규 요청 금지 |
| 원격 성공 / 로컬 저장 실패 | 원래 응답으로 매핑·결과 저장 복구. 자동 unlink 금지 |
4. 연결 해제·재연결·키 교체
진행 중 작업을 먼저 확인한 뒤 대상 고객만 해제합니다.
- reason은 user_request / admin_action / security_incident 중 하나를 쓰세요. 인증서 연결은 그 밖의 문자열을 400으로 거부합니다.
- 해제 후 조회의 404만으로는 소유권, 비활성, 없음을 가릴 수 없습니다.
- 재연결은 새 사용자 의도로 새 operation_id를 저장하고 같은 등록 메서드를 호출한 뒤 반환 ID와 ACTIVE 상태를 대조하세요.
아래 함수는 기존 고객 권한 검사 뒤 호출하는 SDK 연결점입니다.
대표로 지정한 자격증명과 다기관 fan-out 해제
한 인증서로 여러 기관이 연결됐다면 한 건 해제한 뒤 같은 고객의 나머지 account_link_id를 하나씩 probe해 남은 연결을 확인하세요.멀티계정 키에는 연결 목록 조회가 없고, 해제된 연결은 404입니다.
- 비-primary 연결을 한 건 해제하면 서버가 같은 인증서의 나머지 연결까지 함께 비활성화합니다. 그래서 목록을 미리 만들어 순서대로 해제하지 마세요.
- 진행 중 작업이 있는 연결은 그대로 남고, 나머지 연결의 개별 처리가 실패해도 해제 응답에는 나타나지 않습니다.
- 같은 인증서로 연결된 다른 연결이 남아 있으면 대표(primary) account_link_id의 직접 unlink는 거부됩니다(400 VALIDATION_INVALID_FIELD).그때 비-primary 연결을 한 건 해제하면 대표 연결까지 함께 해제됩니다. 대표 연결만 남았으면 직접 해제됩니다. SDK로 만든 연결은 항상 비-primary입니다.
- 이미 비활성인 연결을 다시 해제하면 409 RESOURCE_CONFLICT입니다.
VID 재연결, 인증서 교체 때도 같은 방식을 적용합니다.
| 대상 | 해제 | 재연결 |
|---|---|---|
| 단일 기관만 연결 | 해당 account_link_id unlink | 새 operation_id → link |
| 동일 인증서 다기관 | 한 건 unlink → 나머지 account_link_id를 probe로 확인 | 각 기관별 새 operation_id·VID |
| VID만 갱신 필요 | 위 방식으로 전부 해제됐는지 확인 | 같은 cert bytes·새 VID로 기관별 재연결 |
def unlink_customer(client, account_link_id):
# reason: "user_request" | "admin_action" | "security_incident"
return client.unlink_connection(account_link_id, reason="user_request")
def verify_after_key_change(new_client, account_link_id):
return new_client.probe_connection(account_link_id)키 교체는 새 키 검증, 보호 저장 준비, 설정 전환, 새 SDK 인스턴스 생성, 구 인스턴스 종료 순서이며, 설정 전환은 처음 읽은 설정 버전(expected revision)이 현재와 같을 때만 합니다.고객 연결 매핑은 유지하고 새 키로 probe합니다.
고객 연결은 조직이 아니라 키의 소유자에게 묶입니다.
재발급은 조직의 소유자나 관리자 누구나 신청할 수 있고, 승인하면 새 키의 소유자는 폐기되는 키의 소유자로 유지되므로 누가 신청해도 기존 account_link_id가 새 키에서 그대로 보입니다.
다만 두 경우에는 보이지 않습니다.
- 옛 키의 소유자가 이미 조직을 떠났다면 새 키는 재발급 신청자의 것이 되어, 기존 account_link_id가 모두 404로 보이고 등록 복구 조회도 404가 됩니다.
- 재발급 뒤 키 소유자가 아닌 관리자가 새로 등록한 연결도 이 키에서 보이지 않습니다.
404가 나와도 자동 삭제나 재등록을 하지 말고 아래 5단계의 문의 정보로 알려 주세요.
재발급이 승인되면 구 키가 바로 폐기되어 새 키를 전달받기 전까지 중단될 수 있습니다. SDK는 유예기간을 만들지 않습니다.
키 설정 삭제, 키 폐기, 기관 unlink, 업무자료 삭제는 별개입니다.
5. 지원에 전달할 정보
XBOSS 기술지원 문의로 접수하세요.
- 환경, SDK 버전, 안전한 오류 code, HTTP 상태, request_id, trace_id, 발생 시각을 보냅니다.
- 등록 복구인지 작업 복구인지와 마지막 성공 단계도 적습니다.
- secret, Authorization, 인증서, 개인키, 기관 비밀번호, 고객 결과 원문은 보내지 않습니다.
아래 함수는 예외 객체를 안전한 진단값으로 바꾸는 고객사 연결 예제입니다.
from xboss_multi_account import XbossError
def safe_diagnostic(error: XbossError) -> dict:
return {
"code": error.code, "status": error.http_status,
"outcome_unknown": error.outcome_unknown,
"request_id": error.request_id, "trace_id": error.trace_id,
"retry_after": error.retry_after,
}6. 배포와 적용 확인
현재 버전은 0.1.2 개발 검증본(미리보기)입니다. 정식 배포와 서명, 실제 키를 사용한 전체 연동 검증이 끝나지 않았습니다.
- 예제 ZIP의 OPERATIONS.md에 동시 편집, 키 회수, 업그레이드 계약이 있습니다.
- manifest의 해시는 무결성 확인이며 공식 서명이 아닙니다.매니페스트와 파일을 같은 사이트에서 받았다면 해시가 맞아도 출처 인증은 되지 않습니다.
실제 서비스 도입 전 아래 항목을 고객사 환경에서 검증하세요.
- 첫 고객과 두 번째 고객
데모에서는 사용 허가를 받은 고객별 자료로 연결, 작업 실행, 결과 저장을 해 봅니다. 매핑과 결과가 섞이지 않아야 합니다.
- 종료·응답 유실·동시 요청
기존 요청 ID와 작업을 복구하고 중복 요청·중복 결과 반영을 막는지 확인합니다.
- 권한 회수와 키 교체
화면과 MCP 모두 현재 고객 권한을 적용하고 구 설정의 늦은 응답이 새 설정을 덮지 않게 합니다.
- 해제와 복원
연결 상태, 반환 ID, 사용 계정 수를 확인합니다.