APIエラーとその意味
Didit APIから返されるHTTPステータスが実際に何を意味するかを解説します。401と403はキーと権限の問題、402系は残高の問題、429はレート制限、そしてエラーの本文の読み方まで。
レスポンスの本文を読んでください。 Diditのエラーにはメッセージと、多くの場合、実際の問題を特定する詳細コードが含まれます。ステータスだけで原因がわかることはほとんどありません。401はキーの問題、403は権限または環境の問題、429はレート制限、残高エラーはコードではなくクレジットの問題です。
#まず本文を読む
HTTPステータスはカテゴリーを示すだけです。本文が何が起きたかを教えてくれます。APIインテグレーションで避けられたはずのデバッグ時間のほとんどは、破棄されてしまったレスポンスの中に答えがあったにもかかわらず、ステータスコードだけを見て推測することに費やされています。
- 無効化されたキー、または誤ったアプリケーションのキーが401の通常の原因です。
- Last usedを見れば、自分が送っていると思っているキーが実際に届いているキーかどうかを確認できます。
- キーが漏えいした可能性がある場合はシークレットをローテーションしてください。401の方が情報漏えいよりましです。
失敗したすべての呼び出しについて、すべての環境で、ステータス・ヘッダー・ペイロードを含むエラー本文全体をログに残してください。後で必要になりますし、後から再現するのはずっと大変です。
#各ステータスが通常意味すること
| ステータス | 通常の原因 |
|---|---|
| 400 | 不正な形式のリクエスト - 必須フィールドの欠落、不正なenum値、ネストされたオブジェクトの形式誤りなど |
| 401 | 認証失敗。x-api-keyヘッダーが存在しない、形式が不正、または有効なキーでない |
| 403 | 認証はされているが許可されていない。環境の誤り、キーに与えられていない権限、またはアカウントで有効化されていない機能 |
| 404 | そのリソースが存在しない、あるいは使用しているキーとは別のアプリケーションの下に存在する |
| 409 | 既存の状態との競合。すでに実行済みのアクションなど |
| 422 | リクエストの形式は正しいが、値が受け入れられない - 構文エラーではなくバリデーションエラー |
| 429 | レート制限。詳細は下記参照 |
| 5xx | Didit側の問題。バックオフを入れてリトライし、status.didit.meを確認してください |
#401と403の違い - 知っておくと時間の節約になる
401は、キーがまったく受け付けられなかったことを意味します。x-api-keyを送っているか、値に余分な空白や引用符が入っていないか、そしてAPIキーの代わりにwebhook署名用のシークレットを貼り付けていないかを確認してください。これらは別物であり、よくある間違いです。
403は、キー自体は有効だが、この呼び出しは許可されていないことを意味します。原因は次の3つが多い順にあります。
- 環境の不一致。 サンドボックス専用のフィールド（
sandbox_scenarioなど）はライブアプリケーションでは拒否され、その逆も同様です。ライブとサンドボックスは別々のキーを持つ別々のアプリケーションです。 - 権限の不足。 一部の操作には、あなたのキーやロールが持っていない権限が必要です。持っていないセッション作成・管理権限が必要な場合は、コードの修正ではなくサポートへの依頼になります。
- 機能が有効化されていない。 一部の機能は組織ごとに提供されます。持っているはずの機能で403が出た場合は、呼び出しを書き直す前に問い合わせる価値があります。
見ただけでサンドボックスキーとライブキーを区別する組み込みの方法はありません。そのため、シークレットマネージャーには明確に区別できる名前で保存し、単一の環境変数に「今使っているキー」を持たせないようにしてください。テスト環境にライブキーがあると、実際のクレジットが消費されます。
#存在するはずなのに404になる
セッションやワークフローが404になり、確実に存在するはずだという場合、通常の答えは、認証に使ったキーとは別のアプリケーションの下に存在しているというものです。リソースはそれぞれのアプリケーションに紐づいており、アプリケーションAのキーではアプリケーションBのセッションを見ることはできません。
#残高とクレジットのエラー
クレジット不足で失敗する呼び出しは、コードの問題ではありません。ワークフローに有料機能が含まれていて、残高がそれをカバーできていないということです。これは「APIが壊れた」という報告の中で圧倒的に多いパターンで、原因はほぼ常に、無料だと思っていたワークフローに含まれるホワイトラベル、AML、またはNFCです。「クレジット不足」エラーの直し方をご覧ください。
#429レート制限
制限は識別子ごとに適用されます - x-api-key、キーが送られていない場合はクライアントIPです - スコープごとに独立したカウンターが、60秒のスライディングウィンドウで動作します。
グローバルのデフォルト値は以下のとおりです。
| スコープ | メソッド | 上限 |
|---|---|---|
| 一般的な読み取り | GET | 600 / 分 |
| 一般的な書き込み | POST、PATCH、DELETE | 300 / 分 |
一部の影響の大きいエンドポイントには、グローバルの上限に加えてより厳しい制限があり、先にカウンターを超えたスコープが429を返します。完全な一覧はレート制限をご覧ください。
429にはエクスポネンシャルバックオフとジッターで対応してください。レート制限に対してタイトなリトライループを組むと問題が悪化し、制限が解除されない状態が続くことがあります。
429の典型的な原因はバッチジョブです - 数百件の作成リクエストを数秒のうちに送る夜間インポートなど。エラーが止まるまで並列数を上げるのではなく、処理を時間的に分散させてください。
#機能レベルの詳細コード
HTTPステータスとは別に、個々のチェックはプロバイダー側の問題について独自の詳細コードを返します。例えば、特定の国の特定のプロダクトへのアクセス権を持たないレジストリ連携などです。詳細コードを受け取ったら、そのコードが状況を正確に示しているので、問い合わせの際はそのまま引用してください。
カタログにあるはずの詳細コードがレスポンスに含まれていない場合は、回避策を探すのではなく報告する価値があります。コードの欠落は実際のギャップであり、次にこの問題に当たる人にとっても解決を難しくします。
#空のレスポンスは成功ではない
プロバイダー連携のチェックが空の本文を返すのは、クリーンな結果と同じではありません。「データなし」はパスとして扱うのではなく、コード内で独自のケースとして扱ってください。特にデータベースバリデーションとウォレットスクリーニングでは、未提供のサービスと本当の不一致が外見上似て見えることがあります。
#エラーパスのテスト
サンドボックスは特定の失敗を確定的に発生させることができ、これがエラーハンドリングをテストする唯一の理にかなった方法です。サンドボックスでのテストをご覧ください。