エラーと制限

何かがうまくいかないとき。

エラーは JSON エンベロープで返ります。安定した type、人が読めるメッセージ、そして問題の報告時に添えられる request_id が含まれます。

実際のレスポンス - 無効なキー(HTTP 401)
{"type": "error", "error": {
   "type": "authentication_error",
   "message": "Invalid or revoked API key.",
   "request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
 }}
HTTP意味対処
400不正なボディ(フィールドの欠落・型違い)メッセージに該当フィールドが明記されます - 修正して再試行してください。
401API キーが無効または失効しているキーを確認し、コンソールで新しいキーを発行してください。
402残高不足、カード未登録、またはティア上限コンソールでチャージするか、カードを登録してください。レスポンスに balance_cents と floor_cents が入っているので、どちらに止められたのか判別できます。
404該当する記憶・ストア・画像がないid を確認してください。get_image は、記憶が存在していても画像を持たない場合にも 404 を返します。
409その名前は既に使われているストア名とワークスペース名はアカウント内で一意です - 別の名前を選んでください。
413リクエストボディが 10MB 超過Base64 はエンコード元のファイルより約 33% 大きくなるので、画像は縮小してからエンコードしてください。
429レート制限を超過SDK が既にバックオフとジッターを入れて再試行し、Retry-After も守っています。これを受け取ったということは再試行が尽きたということです - 自前のループで包むのではなく、同時実行数を下げてください。
501このモデルのエンジンがそのエンドポイントを実装していない画像と修正履歴にはより新しいエンジンが必要です。GET /api/v1/models でどのモデルが何に対応しているか分かります。
5xxサーバー側の問題バックオフしつつ再試行してください。ただし闇雲にではありません。この API はすべての呼び出しが POST で、サーバーが既にあなたのリクエストを保存し終えている可能性があるため、SDK は 5xx を自動では再試行しません。送り直すときは冪等キーを付けて二重書き込みを防ぎ、お問い合わせの際は request_id を添えてください。

すべてのエラーは WosError であり、ステータスごとに専用のクラスもあります - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError。数値を比較するのではなく、扱いたいものを捕捉してください。

# SDK error handling (Python)
from wontopos import Client, WosError, RateLimitError, PaymentRequiredError

try:
    mem.search("...", user_id="alice")
except PaymentRequiredError: ...      # 402 - top up
except RateLimitError: ...            # 429 - the SDK already retried; slow down
except WosError as e: ...            # e.status, e.message, e.request_id
except (ValueError, TypeError): ...    # never left the client

一部の誤りは私たちに届くことすらありません。API キー、ストア id、冪等キー、画像はリクエストを送り出す前に検査され、そのときは WosError ではなく ValueError や TypeError が発生します。except WosError だけではこれらを捕捉できません。

キーの安全。キーは作成時に一度だけ表示され、私たちの側にはハッシュとしてのみ保存されます。環境変数に保管し、漏えいした場合はコンソールで失効させてください - 失効は即時です。

レート制限はアカウント単位で、すべてのキーが共有し、ティアに応じて拡大します - 利用ティア を参照してください。アカウントの使用状況はコンソールで確認できます。