ステータスとサポート

エスカレーションの前に切り分ける

報告される障害はほぼすべて5つのいずれかで、それぞれに見分けられる兆候があります：

症状	考えられる原因	参照先
昨日は成功した呼び出しで `401 unauthorized`	キーがローテーションまたは無効化された、あるいは一部のコードパスでヘッダーが欠けている	認証
`402 insufficient_balance`	この送信の予約額を下回る残高	アカウントと残高
単一のリクエストが `200` を返すのに、何も課金されない	組み合わせ全体が失敗した。HTTP ステータスは結果ではない	課金と返金
同じリクエストが、成功と失敗を交互に繰り返す	レート制限、または異なるペイロード間で `Idempotency-Key` が再利用されている	レート制限、冪等性
バルクタスクが `processing` のまま留まり、`last_progress_at` が進まなくなる	遅いのではなく、本当にスタックしたタスク	タスクステータス

last_progress_at のケースは、率直に述べておく価値があります。障害のシグナルは経過時間ではなく、止まったタイムスタンプです。 500,000 行のタスクは、正当に長時間実行されることがあります。last_progress_at が動いていないタスクは、エスカレーションすべきタスクです。

サポート依頼に含めるもの

以下のフィールドはすべて API が返すものなので、含めても手間はかからず、往復を1回節約できます：

含めるもの	入手元
`request_id`	ボディを返した失敗を含む、すべてのリアルタイムレスポンス
`task_id`	すべてのバルク送信と、すべてのタスクステータスレスポンス
`api_key_id`	`GET /v1/api-key` — キーを露出せずに特定します
正確な HTTP ステータスとレスポンスボディ	自分のログ。特に `code` フィールド
秒までの精度を持つ UTC タイムスタンプ	自分のログ
キーを伏せた、送信したリクエスト	自分のコード

サポート依頼に API キーを貼り付けないでください。api_key_id がキーを特定し、キー本体は残高へのアクセスを許可します。

インシデント連絡

アカウント単位の通知（計画メンテナンス、容量低下など）はコンソールに表示され、残高と記録もそこにあります。API は同じ状況を、文章ではなくエラーコードとして、あなたの統合に直接伝えます：

コード	稼働中の統合にとっての意味
`detection_capacity_unavailable`	現在、容量がありません。バックオフして再試行してください。何も課金されていません。
`realtime_route_unavailable`	利用可能なリアルタイムルートがありません。バックオフして再試行してください。
`realtime_rate_limiter_unavailable`	リミッター自体が停止しているため、受け入れ可否を判断できません。後で再試行してください。
`realtime_fact_cache_unavailable`	リアルタイムの依存サービスが停止しています。後で再試行してください。

これらは 503 で、すべて「待ってから再試行」のグループに属します — 同じ Idempotency-Key で安全に再試行できる失敗を含む全体の分類は、エラーコードを参照してください。

プラットフォームの現状

外部から検証できる運用上の事実が2つあり、インシデントを起票する前に知っておく価値があります：

API は Cloudflare の背後で提供されるため、ネットワーク経路と TLS 終端は、単一のオリジンホストではなく Cloudflare によって運用されます。
すべてのレスポンスが X-RateLimit-Remaining を持つため、レスポンスヘッダーを記録するクライアントは、誰かに尋ねることなく「自分の制限によるスロットリング」と「サービスの停止」を区別できます。general と detection のグループは、すべてのレスポンスで X-RateLimit-Limit も持ちますが、リアルタイムは持ちません。固定の毎分上限ではなくトークンバケットを消費するためです。

エラーコード — 最も手早いトリアージテーブルとなる再試行グループ
セキュリティ — キーの扱い、キーのローテーション、決して送ってはならないもの