レート制限と API エラー
Telemetry エンドポイントは、標準の HTTP ステータス コードを使用します。クライアントは、再試行する前に、リクエストの欠陥と一時的なサービスまたは容量の状態を区別する必要があります。
プラン固有の割り当てと現在の制限は変更される場合があります。製品および請求設定に表示される制限を、アカウントの信頼できる情報源として扱います。文書化されていないグローバルリクエストレートをハードコーディングしないでください。
応答クラス
| ステータス | 意味 | クライアントのアクション |
|---|---|---|
200 または 202 |
操作が成功したか、非同期ジョブが受け入れられました | 応答本文を読んで続行します |
400 |
無効な JSON、SQL、テーブル名、フィールド タイプ、またはリクエスト形状 | リクエストを修正します。変更せずに再試行しないでください |
401 |
API キーが見つからない、無効である、または取り消されています | 資格情報を置き換える |
403 |
キーには必要なスコープがありません | 正しいスコープ付きキーを使用する |
404 |
要求されたテーブル、ジョブ、ダッシュボード、アラート、またはルートが存在しません | 識別子とチームを確認する |
409 または 422 |
リクエストは現在の状態と競合しているか、適用できません | エラーを調べて動作を変更する |
429 |
現在のリクエストレートまたはクォータを超えました | 尊重する Retry-After 存在するときと離れるとき |
5xx |
Telemetry は有効なリクエストを完了できませんでした | バックオフを使用して制限された回数だけ再試行します |
エラー本文には、より具体的なコンテキストが含まれる場合があります。ステータス、エンドポイント名、リクエスト ID、および安全なエラー カテゴリをログに記録します。リクエストが失敗したからといって、API キーや元のイベント ペイロードをログに記録しないでください。
匿名トライアルのエラー
anon_… キーでは、HTTP ステータスだけでなく JSON の code も確認してください。403 がキーの誤りを意味するとは限らず、すべての 429 が待機で解決するわけではありません。
| コード | ステータス | 対処 |
|---|---|---|
anonymous_signup_required |
403 |
最初のイベントから 24 時間の匿名読み取り期間が終了しました。応答の非公開 signup_url で既存のワークスペースをアカウントに紐づけ、データを保持してください。イベントを取り戻すためにキーを交換したり、別のトライアルを作成したりしないでください。 |
anonymous_account_required |
403 |
この機能にはアカウントが必要です。トライアルを紐づけて同じワークスペースを使い続けてください。 |
anonymous_rate_limited |
429 |
待機してから、待機時間を延ばしつつ回数を制限して再試行してください。 |
anonymous_table_limit または anonymous_free_limit |
429 |
トライアルのテーブル数または使用量の上限に達しました。ワークスペースを紐づけ、アカウントの上限を確認してください。待つだけではトライアルの利用枠は回復しません。 |
anonymous_invalid_batch |
413 |
バッチを小さくし、応答メッセージに従ってテーブル名を確認してから再試行してください。 |
anonymous_expired |
410 |
未紐づけのトライアルは期限切れで、紐づけによる復旧はできません。アカウントで最初から始め、このキーでの再試行を止めてください。 |
紐づけ用リンクは非公開情報です。signup_url を公開チケットやログに載せないでください。別のブラウザーでは、紐づけページを開き、既存の匿名 API キーを入力するオプションを使ってください。紐づけるとワークスペースとキーが保持されます。
安全に再試行してください
ジッターを伴う指数バックオフを使用する 429, 502, 503、そして 504 応答。テレメトリの停止によってアプリケーション ワーカーが疲弊することがないように、試行時間と合計経過時間の両方に制限を設けます。
delay = min(max_delay, base_delay * 2^attempt) + random_jitter
再試行しないでください 400 リクエストを変更せずに応答します。無効なスキーマまたは SQL クエリを繰り返し送信すると、成功へのパスが作成されずに負荷が発生します。
イベントのアイデンティティを保持する
取り込みを再試行するときは、安定した event_id 論理イベントの場合。これにより、重複配信が測定可能になり、冪等のコンシューマが再試行を認識できるようになります。ネットワークを試行するたびに新しい識別子が発生し、1 つの結果がいくつかの区別できないビジネス イベントに変わります。
を使用します。 重複したイベント ID レシピ 再試行動作を監査します。
バウンド障害の影響
テレメトリがクリティカル パス上にあるかどうかを決定します。ほとんどの製品インストルメンテーションでは、一時的な取り込みの失敗は、既に成功した顧客の応答を変更することなく、安全な診断チャネルを通じて報告される必要があります。コンプライアンスまたは請求のワークフローには、永続的なキューが適切な場合があります。
大規模な結果セットの場合は、 非同期クエリ API 対話型リクエストを繰り返し再試行するのではなく、参照 API キーと認証 スコープルールの場合。