오류 코드 ​

DAT 에서 공식 지원하는 서비스 라이브러리의 공통 오류코드입니다.

각 코드에는 영향·재시도 두 값이 붙고, 일부에는 의심 딱지가 추가로 붙습니다.

영향 — 서비스가 받는 타격 ​

알람을 걸 기준입니다. "지금 서비스가 멈췄나"만 봅니다.

영향 없음 은 알람 대상이 아닙니다. 잘못된 입력이 한 번 들어온 것을 담당자 전원이 확인해야 한다면 알람이 무의미해집니다.

의심 — 지속되면 조사 ​

의심 딱지가 붙은 코드는 한 건일 때는 정상 운영의 일부입니다. 클라이언트는 언제든 잘못된 값을 보낼 수 있고, 라이브러리가 걸러내는 것이 제 역할입니다.

다만 이런 오류가 지속적으로, 또는 특정 출처에서 몰려서 발생한다면 두 가지 중 하나입니다.

• 설정 이상 — 배포가 잘못됐거나, 구버전 클라이언트가 남아 있거나, 인증서가 어긋나 있습니다.
• 해킹 시도 — 토큰·키를 조작해 검증을 통과시키려는 시도이거나, 유효한 값을 찾는 탐색입니다.

그래서 이 코드들은 건수를 지표로 잡아 두는 것이 맞습니다. 임계치를 넘을 때만 알리면 됩니다.

재시도 ​

토큰 ​

받은 토큰 문자열 자체의 문제입니다.

인증서 ​

인증서 문자열의 형식, 그리고 그 인증서를 지금 쓸 수 있는지의 문제입니다.

DAT_CERT_NOT_FOUND와 DAT_CERT_NOT_SYNCED는 겉보기 증상이 같지만 대응이 다릅니다. 전자는 우리가 발급한 적 없는 cid라 기다려도 안 생기고, 후자는 동기화만 되면 풀립니다.

DAT_CERT_NOT_FOUND는 한 건이면 그냥 걸러 내면 되지만, 갑자기 늘어나면 배포가 어긋났거나 위조 토큰이 돌고 있다는 뜻입니다.

서명 ​

암호화 ​

secure 페이로드의 암·복호 문제입니다.

빈 secure 페이로드는 오류가 아닙니다. 빈 입력은 빈 출력이 되며 어떤 코드도 내지 않습니다.

서명 검증을 건너뛰는 경로에서는 GCM 태그가 유일한 무결성 검사입니다. 그래서 DAT_CRYPTO_TAG_MISMATCH를 다른 복호화 실패와 같은 코드로 묶지 않습니다.

키 ​

비슷해 보이지만 다른 셋:

매니저 ​

인증서를 보유하고 발급·검증에 쓰는 객체의 상태입니다.

DAT_MANAGER_NO_ISSUABLE_CERTIFICATE의 사유(cause)는 넷 중 하나입니다. 원인마다 해야 할 일이 전혀 다릅니다.

발급 서버가 검증 전용 인증서만 받도록 설정되면 DAT_CERT_VERIFY_ONLY가 나옵니다. 기다려도 절대 안 풀리므로 재시도 대상이 아닙니다.

설정 ​

호출자가 넘긴 값의 문제입니다. CONFIG 계열은 전부 코드를 고쳐야 하는 오류이며, 운영 중에 나면 배포가 잘못된 것입니다.

내부 ​

실행 환경과 런타임의 문제입니다.

DAT_INTERNAL_UNAVAILABLE은 배포 환경을 고치면 해결되고, DAT_INTERNAL_UNKNOWN은 대개 런타임 장애이거나 라이브러리 버그입니다.

CMS 동기화 ​

CMS 동기화를 쓰지 않으면 이 코드는 나오지 않습니다.

동기화가 영구 실패로 판정되는 코드(UNAUTHORIZED·FORBIDDEN·ENDPOINT_NOT_FOUND·MALFORMED·IMPORT_FAILED)는 전부 치명입니다. 재시도해도 안 풀리는데 인증서는 계속 만료되므로, 방치하면 서비스가 반드시 멈춥니다.

반대로 UNREACHABLE·SERVER_ERROR 는 부분입니다. 기존 인증서로 계속 동작하고 다음 주기에 자가 회복합니다 — 다만 계속 실패하면 결국 치명으로 넘어갑니다. 연속 실패 횟수를 기준으로 알람을 거십시오.

서버 ​

CMS 서버가 내는 코드입니다. 클라이언트는 이 코드를 만들지 않고 수신만 합니다.

응답 봉투:

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

인증서를 만들고 다루다 나는 오류는 서버도 위의 공통 코드(DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*)를 그대로 씁니다.

서버 코드를 받으면 ​

클라이언트는 서버 코드를 자기 쪽 CMS 코드로 감싸고, 원본은 cause에 보존합니다.

증상으로 찾기 ​

부록 ​

코드 문법 ​

DAT_<영역>_<원인>

• 같은 원인이 서로 다른 영역에서 나면 원인 이름이 같습니다. DAT_TOKEN_MALFORMED와 DAT_CERT_MALFORMED는 대상만 다르고 뜻이 같습니다.
• _UNKNOWN은 각 영역의 폴백 전용입니다. "알 수 없는 알고리즘"처럼 다른 뜻으로 쓰지 않습니다(그건 _UNSUPPORTED입니다).
• 코드 문자열은 공개 계약입니다. 메시지는 자유롭게 바꿔도 되지만 코드는 바꾸지 않습니다.

클라이언트별 접근 방법 ​

보안 이벤트 는 위조·변조가 확정적인 두 건(DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH)만 true 를 돌려줍니다. 이 문서의 의심 딱지는 그보다 넓은 범위(조작된 토큰·키·요청까지)이며, 지금은 문서 분류일 뿐 클라이언트 API 로는 노출하지 않습니다.

영향 등급도 마찬가지로 문서 분류입니다. 같은 코드라도 어디서 났는지에 따라 타격이 달라지기 때문입니다 — 예를 들어 DAT_KEY_INVALID 는 들어온 토큰을 거를 때는 영향이 없지만, CMS 동기화 중 인증서를 읽다 나면 동기화가 통째로 실패합니다.

하위 원인은 버려지지 않습니다. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE와 DAT_CMS_IMPORT_FAILED는 각 언어의 예외 체이닝(cause / __cause__ / InnerException / Unwrap())으로 사유를 전달합니다.