429 Too Many Requests の原因と対処｜API の 3 つの上限の見分け方

429 Too Many Requests は、サーバーが「今はこれ以上のリクエストを受け付けられない」ことを示す HTTP の状態コードです。多くの API は、短い時間に呼ばれすぎたとき (レート制限) にこのコードを返します。

avacast の API では、429 を返す理由が 3 つあり、エラーの code で見分けられます。理由によって対処が違うため、状態コードだけで判断せず、code を見て処理を分けます。

429 の 3 つの理由

エラーの応答は {"error":{"code","message"}} の形です。

HTTP/1.1 429 Too Many Requests
Retry-After: 2

{ "error": { "code": "rate_limited", "message": "..." } }

rate_limited: 呼び出しが多すぎる

短い時間に同じ API キーで多くのリクエストを送ると返ります。応答の Retry-After に、待つべき秒数が入っています。その秒数が過ぎてから送り直します。

すぐに送り直すと、また 429 になります。ループで呼んでいる処理がないか、セッションの状態を短い間隔で何度も取りに行っていないかを確かめます。待ち方は指数バックオフで再試行するで説明しています。

concurrency_limit: 同時に開けるセッションの上限

同時に開けるセッションの数はプランで決まっています。

• Free: 同時 2 セッション
• Starter: 同時 5 セッション
• Standard: 同時 20 セッション
• Business: 同時 40 セッション

上限に達しているときに POST /v1/sessions を呼ぶと、concurrency_limit になります。待っていても空かないことがあるため、再試行よりも、使い終わったセッションを閉じることが先です。

• 画面を離れたときに DELETE /v1/sessions/:id を呼んでいるか
• 開発中のリロードで、閉じていないセッションが残っていないか
• 混む時間の同時数に対して、プランが足りているか

閉じ忘れても、無発話が続くか最大長に達すると自動で閉じます。閉じ方の設計はセッションの閉じ忘れを防ぐにまとめています。

queue_full: 発話がたまりすぎている

speak は前の発話の完了を待たずに呼べますが、未再生と再生中の発話は 1 セッションあたり 20 件までです。超えると queue_full になります。

長い文章を細かく分けて一度に送ると起きやすくなります。speak.ended や queue.drained のイベントを待ってから次を送るか、話の流れが変わったときは POST /v1/sessions/:id/interrupt で未再生の発話を捨ててから送ります。

利用者への見せ方

• rate_limited: 数秒待って自動でやり直し、利用者には「少々お待ちください」と表示する
• concurrency_limit: 「ただいま混み合っています」と表示し、少し時間をおいて開き直す
• queue_full: 利用者からは見えにくいため、送る側の処理を直す

サーバー SDK (Node.js・Go・PHP) は 429 のときの再試行を持っています。それでも続く場合は、上の表で理由を確かめてください。

よくある質問

429 が返ったら、すぐに送り直してよいですか。

rate_limited の場合は、Retry-After の秒数だけ待ってから送り直します。concurrency_limit と queue_full は、待つだけでは解消しないことがあるため、セッションを閉じる、キューを空けるといった対処を先に行います。

同時セッション数を増やすにはどうすればよいですか。

上位のプランに変えると、同時に開けるセッションの数が増えます。プランは管理画面からいつでも変えられ、上位のプランへは即時に切り替わります。

429 になったリクエストは課金されますか。

課金はセッションを開いていた時間です。429 で作られなかったセッションには、接続時間がありません。