1. 質問
あるB2BデータAPIが数千の開発者チームに利用されています。あるリリース以降、リクエストが失敗しても修正方法が説明されていないというサポートチケットが増加しています。エンジニアリングチームはより多くの内部ログを開示したいと考え、セールスチームは顧客ごとにカスタムのエラーメッセージを求めています。プロダクトマネージャーとして、既存のクライアントを破壊することなく、アクションにつながるAPIエラー体験を設計してください。
2. 制約と確認事項
- クライアントの入力、認証・認可、レート制限、依存関係、内部サービスの失敗を分離し、すべての失敗をひとつの500にまとめないこと。
- レスポンスが、機械による処理、開発者による診断、エンドユーザーへの表示のそれぞれのニーズを混同することなく満たせるようにすること。
- 既存のSDKやログ形式をすべて即座に変更することはできないため、計画では古いクライアントと段階的な移行をサポートする必要があります。
- 機密性の高いスタックトレース、トークン、ユーザーデータ、内部トポロジーを呼び出し元に直接返してはなりません。
3. プロダクト診断フレームワーク
問題を3つの問いに分割します：何が起きたのか、誰が修正できるのか、次に何をすべきか。エラーレスポンスには、機械可読な安定したコード、安全な人間向けサマリー、任意の構造化された詳細、サポート用の相関IDが必要であり、ドキュメントとSDKがコードを修正方法へとマッピングします。プロダクト分析では、単なる全体的な失敗率だけでなく、エラー後の復旧率、繰り返されるリトライ、失敗から成功までの時間、エラー分類ごとのサポートチケット数、バージョン分布を追跡する必要があります。
4. 参照ソリューション
errorResponse:
status: canonicalStatusCode
code: stableProductErrorCode
message: safeHumanSummary
details:
reason: machineActionableReason
fieldViolations: optionalFieldErrors
retryAfter: optionalDelay
requestId: supportCorrelationId
docsUrl: versionedFixGuide
clientFlow(error):
classify(error.status, error.code)
if retryable: backoffAndRetry(error.details.retryAfter)
else if fieldError: highlightFields(error.details.fieldViolations)
else: showDocsAndRequestId(error.docsUrl, error.requestId)安定した標準ステータスコードの小規模なセットを定義し、アクション可能な原因にはプロダクトエラーコードを使用します。フィールドの違反内容、リトライのタイミング、ドキュメントへのリンクは構造化された詳細に配置します。コンソールにはコードごとの修復手順が表示され、SDKはエラーをキャッチ可能な型にマッピングしつつ元のコードを保持します。サービスは完全な診断情報を内部に記録しますが、返却するのは安全なサマリーと相関IDのみにとどめます。
5. トレードオフとロールアウト戦略
エラーコードをより細かく定義するとガイダンスはより正確になりますが、互換性とドキュメントのコストが増加します。開発者が修正可能な発生頻度の高いエラーから着手し、その後小さな分類の詳細を追加します。テナントごとにカスタムプロトコルを作成してはなりません。新しいフィールドは下位互換性を保つ必要があります。コードの意味が一度公開されたら安定して維持します。古いクライアントは引き続き古い形式を受け取り、新しいSDKは構造化された詳細をオプトインします。部分的な失敗（partial-failure）のレスポンスはクライアント側の分岐処理を増やすため慎重に扱う必要があります。バッチAPIにおいて明確な必要性がある場合にのみ導入してください。
6. 検証と可観測性
- サポートチケットと呼び出しログをサンプリングし、各失敗を「診断可能」「修正可能」「不要にリトライされたか否か」でラベル付けします。
- 認証、フィールドバリデーション、レート制限、依存関係のタイムアウト、未知の失敗に対するコントラクトテストを作成し、ステータス、コード、ドキュメントURLをチェックします。
- 新しい形式を段階的にロールアウトし、復旧率、繰り返されるリトライ、チケット数、SDKの例外キャプチャ率を比較します。
- 未知のコード、古いクライアントの割合、ドキュメントクリックから成功へのコンバージョン、エラーレスポンスにおける機密フィールドの漏洩を監視します。
7. よくある間違い
- 呼び出し元に安定したコードと修復アクションを提供することなく、より多くのログやスタックトレースを開示してしまうこと。
- すべてのビジネス的な意味をHTTPステータスにエンコードし、クライアントに文字列パースを強いること。
- 親切なメッセージと称して、内部例外、トークン、または完全なリクエストパラメータを含めてしまうこと。
- あるリリースでコードの名前変更や削除を行い、アップグレード時に古いSDKを破損させること。
8. 面接の評価ポイント
修復の責任者ごとにエラーを分類しているか
候補者は入力、権限、レート制限、依存関係、内部の失敗を分離し、それぞれに対する呼び出し元のアクションとサービス側の責任を明記する必要があります。
安定して安全なエラーモデルを設計しているか
回答には、機械可読なコード、安全なサマリー、構造化された詳細、相関ID、バージョン管理されたドキュメントが含まれ、内部情報が開示されていない必要があります。
体験をプロダクトメトリクスに結び付けているか
候補者は、失敗率単独ではなく、復旧率、繰り返されるリトライ、修正までの時間、チケット、バージョン分布を活用する必要があります。
互換性のある移行を計画しているか
候補者は、古い形式との互換性、SDKの段階的な適用、ロールアウトとロールバックの基準、および複雑な部分失敗プロトコルの導入を避けるべきタイミングについて説明する必要があります。