エラー、制限、再試行

API クライアントは、HTTPステータスコード、安定したエラーコード、およびレスポンスヘッダーに基づいて判断を行う必要があります。プラン名によるクォータ値をハードコーディングしないでください。ゲートウェイおよびサービスの制限は、アクティブなプラン、管理者の設定、プロファイル、および現在の製品ポリシーによって決定されます。

エラー・エンベロープ

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope.",
    "status": 403
  }
}

一部のプロキシ経由のサービスでは、サービス固有のエンベロープが返される場合があります。構造化された診断ログには、常に HTTPステータスとレスポンス本文を保持しますが、認証情報や機密性の高いユーザーデータは伏せてください。

一般的なステータス

ステータス	意味	クライアントの対応
`400`	無効なリクエスト形式またはパラメータ	リクエストを修正してください。変更せずに再試行しないでください。
`401`	資格情報の欠落、無効、有効期限切れ、または取り消し	資格情報を置き換えるか、更新してください。
`403`	スコープ、サービス、ロール、プラン、クォータ、IP、またはリソースポリシーにより、操作が拒否されました	エラーコードと現在のアカウント設定を確認してください。
`404`	ルートまたは要求されたリソースが見つかりませんでした	バージョンAPI、パス、識別子、およびリソースの可視性を確認してください。
`409`	この操作は、現在のリソースの状態と競合します	再試行するかどうかを決定する前に、状態を更新してください。
`429`	1分ごとまたは1日ごとのリクエスト制限に達しました	待機する `Retry-After`; 並行処理やポーリングの頻度を減らしてください。
`500`	リクエストが、予期せず失敗したサービスに到達しました	操作の繰り返しに問題がない場合にのみ、再試行を行ってください。
`502`, `503`, `504`	依存関係、制御、またはサービスが一時的に利用できませんでした	ジッターを伴う有界指数バックオフを適用してください。

ゲートウェイのエラーコードには、以下のものが含まれる場合があります。 MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE、および INTERNAL_ERROR。宛先サービスは、独自のリソースやクォータに関して追加のコードを返す場合があります。

有効期限付きリミットヘッダー

認証済みのリクエストのうち、成功したものや拒否されたものには、次のようなものがあります：

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

これらの値は実行時に読み取ってください。制限はプラン、アカウント、プロファイル、管理者ポリシー、およびリリース段階によって異なり、クライアントのリリースなしに変更される場合があります。

再試行戦略

一時的なステータスに対しては、ジッターを伴う有界指数バックオフを使用してください。実用的なシーケンスは 1 秒付近から始まり、適度な最大遅延に達するまで増加させます。指定されている場合は、より大きな値を優先してください。 Retry-After 値が指定されている場合は、その値に従ってください。

操作が安全である場合にのみ再試行してください：

GET リクエストは通常、再試行しても問題ありません。
作成、送信、または更新の失敗は、接続が失敗する前に完了している可能性があります。再試行する前に、リソースの状態を確認してください。
再試行しないでください 400, 401、またはほとんどの 403 リクエストや認証情報を変更することなく、レスポンスを処理できます。
最大試行回数を設定し、その回数に達した際には適切なエラーメッセージを表示してください。

不要なトラフィックを削減する

読み取り専用の権限情報やメタデータのレスポンスは、UI操作のたびに確認するのではなく、適切な短期間だけキャッシュしてください。
優先してください Webhook でサポートされているイベントをご確認ください。
同じワークロードからの同一のリクエストは統合してください。
大規模なコレクションはページネーションを行い、無制限の同時実行は避けてください。
CLI’s’ を使用してください。 --json 書式設定のために重複したAPI リクエストを送信するのではなく、スクリプト内で出力を行ってください。

予期しない拒否の診断

呼び出し GET /v1/auth/whoami で、有効なIDとキーを確認してください。
呼び出し GET /v1/auth/quota 現在のゲートウェイのクォータのスナップショットについては、こちらをご覧ください。
キーに、そのルートに必要なスコープが設定されていることをご確認ください。
宛先サービスがアクティブなプロファイルで有効になっていることをご確認ください。
宛先サービスにおけるロールおよび組織の権限をご確認ください。
お問い合わせいただく前に、ステータス、エラーコード、レスポンスヘッダー、およびリクエスト時刻を記録してください。 CHAMPREP サポート.