CAPTCHA API の HTTP 402・429・503 エラー処理

HTTP とエラーコードを両方確認

エラー本文は {"error":"CODE"} 形式で、X-Request-ID ヘッダーが調査用の識別子です。taskId と共にローカル保存し、認証情報やタスク本文を公開ログに出さないでください。

応答	意味と次の操作
400 INVALID_TASK	項目と型を修正。不正な JSON は再送では直りません。
401 / 403	Key の期限、権限、IP 制限、アカウント状態を確認。
402 INSUFFICIENT_BALANCE	利用可能残高が不足。予約済み金額も考慮。
409 IDEMPOTENCY_CONFLICT	元のキーと本文を比較。
429	頻度・並列数を下げ、Retry-After に従う。
503 TYPE_UNAVAILABLE	利用可否を確認し、無効な種類への連続送信を停止。
503 DATABASE_BUSY	元のキーと本文で再送。確定結果の照合が必要な場合があります。

制限ごとに対処が異なります

KEY_CONCURRENCY_LIMIT では既存タスクの完了を待ちます。KEY_SPEND_LIMIT は移動時間窓の支出制限で、連続再送では解決しません。KEY_QUOTA_EXHAUSTED は一時的な 429 ではなく総利用枠の 403 です。詳細は API エラー一覧を参照してください。

再試行に上限を設定

通信障害、待機可能な制限、再試行可能なサーバー障害だけを対象にします。Retry-After（秒数または HTTP 日付）を守り、回数を制限し、待ち時間が残り予算を超えたら停止します。POST の本文とキーは固定し、GET は同じ ID を照会します。

タスク状態の失敗は別の層です

照会が HTTP 200 でも status=failed や status=uncertain の場合があります。HTTP コードに加え状態と公開エラーを確認します。failed/cancelled は終了、uncertain は照合を継続し予約額が残ることがあります。安全なポーリングを確認してから自動再送を実装してください。