エラーコード ​

DAT が公式にサポートするサービスライブラリ共通のエラーコードです。

各コードには 影響・リトライ の 2 つの値が付き、一部にはさらに 疑い のタグが付きます。

影響 — サービスが受ける打撃 ​

アラートを設定する基準です。「いまサービスが止まっているか」だけを見ます。

影響なし はアラートの対象ではありません。不正な入力が 1 件来ただけで担当者全員が確認しなければならないなら、アラートは意味を失います。

疑い — 続くようなら調査 ​

疑い タグが付いたコードは、1 件だけなら通常運用の一部です。クライアントはいつでも不正な値を送ってくる可能性があり、それを弾くのがライブラリ本来の役目です。

ただしこうしたエラーが継続的に、あるいは特定の発信元からまとまって発生する場合は、次の 2 つのどちらかです。

• 設定の異常 — デプロイが誤っている、旧バージョンのクライアントが残っている、証明書が食い違っている。
• 攻撃の試み — トークンや鍵を改ざんして検証を通そうとしている、あるいは有効な値を探る探索行為。

そのためこれらのコードは 件数をメトリクスとして取っておくのが正解です。しきい値を超えたときだけ通知すれば十分です。

リトライ ​

トークン ​

受け取ったトークン文字列そのものの問題です。

証明書 ​

証明書文字列の形式、およびその証明書がいま使えるかどうかの問題です。

DAT_CERT_NOT_FOUND と DAT_CERT_NOT_SYNCED は外から見た症状は同じですが、対応が異なります。前者はそもそも発行されていない cid なので待っても現れず、後者は同期さえ済めば解消します。

DAT_CERT_NOT_FOUND は 1 件なら弾くだけで済みますが、急に増えた場合は配布が食い違っているか、偽造トークンが出回っているという意味です。

署名 ​

暗号化 ​

secure ペイロードの暗号化・復号の問題です。

空の secure ペイロードはエラーではありません。 空の入力は空の出力になり、コードは一切出ません。

署名検証をスキップする経路では、GCM タグが唯一の完全性チェックです。そのため DAT_CRYPTO_TAG_MISMATCH を他の復号失敗と同じコードにまとめていません。

鍵 ​

似て見えるが別物の 3 つ:

マネージャー ​

証明書を保持し、発行・検証に使うオブジェクトの状態です。

DAT_MANAGER_NO_ISSUABLE_CERTIFICATE の理由 (cause) は 4 つのうちのいずれかです。原因ごとにやるべきことがまったく異なります。

発行サーバーが検証専用の証明書だけを受け取るよう設定されていると 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 です)。
• コード文字列は公開された契約です。メッセージは自由に変えてよいですが、コードは変えません。

クライアント別のアクセス方法 ​

セキュリティイベント は偽造・改ざんが確定的な 2 件 (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()) で理由を伝えます。