WaveSpeedAI

WaveSpeed API認証とエラーハンドリング: 401、429、5xxエラーをプロのように解決

WaveSpeed API認証とエラーハンドリング: 401、429、5xxエラーをプロのように解決

こんにちは、私はドラです。楽しむためにAPIを壊しているので、あなたはそうしなくても大丈夫です。

先週、401エラーが頻繁に出ていました。謎めいた種類ではなく、ばかげた種類です。何か問題があるのは分かっていても、それが何なのか見当がつきません。ヘッダーでX-API-Keyを使っていたことがわかりました。WaveSpeedはAuthorization: Bearerを求めています。小さな違いです。2時間無駄にしました。

APIの認証についての問題はこれです。正しいときはそっと動き、間違っているときは大きく失敗します。そしてWaveSpeedは、ほとんどの最新APIと同様に、余地をあまり与えません。過去数ヶ月、WaveSpeedのAPIを画像とビデオ生成に使うことで学んだことです。そして、何か壊れたときに実際に役立ったことです。

WaveSpeed APIの認証が実際にどのように機能するか

WaveSpeedはベアラートークン認証を使います。すべてのリクエストに必要なもの：

  • Authorization: Bearer <YOUR_API_KEY>
  • Content-Type: application/json

形式は簡潔です：

Authorization: Bearer your_api_key_here
Content-Type: application/json

X-API-Key、Api-Key、またはそれを引用符で囲もうとする人を見てきました。WaveSpeedの公式ドキュメントとサンプルは、ベアラートークン形式を一貫して示しています。それだけです。変種はありません。

APIキーの取得

あなたのAPIキーはwavespeed.ai/accesskeyのWaveSpeedダッシュボードにあります。生成できる前にアカウントをトップアップする必要があります。無料層ユーザー向けのキーはありません。

キーをコピーするときは、余分な空白に注意してください。2回やりました。末尾にスペースをつかんで、気づく前に20分デバッグするのに費やしました。

WaveSpeed APIの認証フロー

トークン更新はありません。OAuthもありません。中間ステップもありません。ベアラートークンを送信し、WaveSpeedがそれを検証して、リクエストが進行するか401で拒否されるかです。

認証に失敗した場合、すぐに401レスポンスが返されます。エラーは通常「invalid authentication」と言い、キーを確認するよう指示します。

401 Unauthorizedエラーの処理

WaveSpeedからの401は、Authorization headerを見て「これは認識できない」と言ったことを意味します。

一般的な原因チェックリスト

通常の容疑者：

  • 間違ったheader形式（Authorization: Bearerを使用していない）
  • 末尾のスペースまたはラインブレークでコピーされたAPIキー
  • ダッシュボードで再生成されたキーだが、古いキーがまだコードにある
  • 環境変数が読み込まれていない
  • アカウントのトップアップなし。クレジットを追加しないとキーが生成されません

クイックフィックス

401に当たったときは、ここから始めます：

まず、正確なheaderをログに記録します。私が送信していると思うもの、つまり実際にHTTPリクエストにあるもの。多くの場合、ベアラートークンが不正な形式であるか、headerの名前が少し異なっています。

次に、ダッシュボードからキーを新しくコピーします。コードに入れる前にcurlで即座にテストします：

curl -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-dev" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test"}'

curlが機能する場合、問題はアプリケーションコードにあります。curlが失敗する場合、キー自体が間違っています。

3番目に、アカウント残高をチェックします。WaveSpeedはクレジットベースのモデルで動作します。残高がゼロに達すると、APIコールが失敗する可能性があります。

429レート制限レスポンスの管理

WaveSpeedのレート制限は階層化されています：Bronze（基本制限、100ドルトップアップ）、Silver（より高い同時実行性、1000ドルトップアップ）、Gold（カスタム、10000ドル以上）。各階層には異なるスループットと同時タスク制限があります。

具体的は公式ドキュメントに正確な数値で記載されていませんが、パターンは明確です。あまりにも速く多くのリクエストを送信すると、429が返されます。

レート制限の理解

FAQによると、サンプル制限には、Bronzeが毎分10画像/ 5ビデオで最大3つの同時タスク、Silverが毎分500画像/ 60ビデオで最大100の同時実行、**Goldが毎分2000画像/ 120ビデオで最大200の同時実行が含まれます。

**「Too Many Requests」**エラーが出ている場合、あなたの階層制限に達している可能性が高いです。スロットリングを防ぐため、プランのアップグレードを検討してください。

リトライのための指数バックオフ戦略

429に当たったとき、リトライする前に待ちます。すぐではなく —それは単に別の429になります。指数バックオフを使用します：

  • 最初のリトライ：1秒待つ
  • 2番目のリトライ：2秒待つ
  • 3番目のリトライ：4秒待つ
  • 3回の試行後、停止して失敗をログに記録

多くのAPIには、待つべき正確な時間を指示するRetry-After headerが含まれています。存在する場合はそれを確認して、その値を使用してください。

クライアント側のリクエストキューの設計

バッチ操作（バッチジョブで100枚の画像を生成するなど）では、階層制限を尊重するキューを追加しました：

  • 現在のタイムウィンドウで送信したリクエストの数を追跡
  • 制限に近づいたら（たとえば、階層のスループットの90%）、新しいリクエストを一時停止
  • タイムウィンドウがリセットされたときに再開

これはほとんどの429が発生する前に防ぎます。複数のプロセスが同時に実行されるときは時々当たりますが、リトライロジックがそれらを処理します。

5xxサーバーエラーへの対応

サーバーエラーは異なります。401または429は、私が何か間違っていることです。WaveSpeedからの500または503は、向こう側で何か壊れたことを意味します。

安全なリトライパターン

5xxエラーの場合、リトライは安全です。ほとんどのサーバーエラーは数秒以内に解決します。Microsoftのドキュメントからの良いパターンは、一時的なエラーの場合を想定して即座に一度リトライし、続く場合は指数バックオフにフォールバックすることです。

私のアプローチ：

  • 即座に一度リトライ（ひょっとしてハイキューかもしれません）
  • それが失敗する場合、429と同じ指数バックオフを使用
  • 合計3回のリトライで上限
  • 失敗をログに記録して続行

GETリクエスト（生成ステータスの確認）の場合、リトライは常に安全です。

POSTリクエスト（新しい生成を開始）の場合、私はより慎重です。同じジョブを誤ってを2回開始したくはありません。

タイムアウトを効果的に構成する

2つのタイムアウトを設定します：

  • 接続タイムアウト： 5秒
  • 読み込みタイムアウト： 30秒

WaveSpeedは画像では「2秒以下」、ビデオでは「約2分」を目指しており、実際の時間はモデル、解像度、負荷によって異なります。

ほとんどの画像生成は5秒以内に完了します。ビデオはより長くかかります。時には60～90秒。ただし、画像でも20秒以上にスパイクすることを見たことがあります。

タイムアウトがなければ、遅いリクエストは無期限にハング可能性があります。タイムアウトがあれば、クリーンエラーが得られ、リトライできます。

WaveSpeed APIのロギングと可観測性

認証とエラー処理が機能したら、それが機能し続けていることを知る必要がありました。

ログに記録する内容

すべてのWaveSpeed API呼び出しについて、ログに記録します：

  • 呼び出されているモデルエンドポイント
  • HTTPステータスコード
  • レスポンスタイム（ミリ秒）
  • リトライであるかどうか、および試行番号

WaveSpeedサポートに失敗したリクエストについて連絡するとき、彼らはジョブIDとタイムスタンプを尋ねます。デバッグのためにこれらをログに保持します。

アラート閾値

私はこれらのアラートを設定します：

  • 401エラー率が1%を超える（認証が壊れている）
  • 429エラー率が5%を超える（一貫してレート制限に当たっている）
  • 任意の5xxエラー（まれであるべき）
  • 平均レスポンスタイムが10秒を超える（潜在的なパフォーマンスの問題）

これらは普遍的な閾値ではありません。私の使用方法に意味を成したものです。重要なことは、ユーザーが気づく前に調査をトリガーする閾値を持つことです。

WaveSpeed API認証本番環境チェックリスト

本番環境に行く前に：

  • APIキーが環境変数に保存され、コードに保存されていない
  • Authorization: Bearer形式を正しく使用している
  • Content-Type headerがapplication/jsonに設定されている
  • 429と5xxのリトライロジック（指数バックオフ）
  • タイムアウト設定（5秒接続、30秒読み込み）
  • ロギングにはステータスコード、レスポンスタイム、ジョブIDが含まれている
  • エラー率スパイクのアラートが設定されている
  • レート制限はクライアント側で設定され、階層制限内に留まる
  • 残高監視がクレジット使用状況の追跡に統合されている

トラフィックスパイク中に時々429が出ます。そして先月WaveSpeedが簡潔な問題を抱えていたときに、いくつかの5xxエラーを見ました。しかし、このセットアップがあれば、これらのエラーはカスケードしません。

認証はほとんど、ただ動くことで動きます。取り組みは、それが動かないときを処理することに行きます。クリーンに、予測可能に、朝の2時に起こされることなく、クレジット残高がゼロになったからです。

💡 問題に直面していますか？

エラーコード＋リクエストIDをコメントに投稿し、トラブルシューティングチェックリストを使用してルート原因の特定を支援します。

**ヒント：ほとんどのエラーはクライアント側で制御可能（headers、APIキー、レート制限）ですが、このプロセスはWaveSpeedサポートが必要な問題を特定するのにも役立ちます。