SquareCloudAPIError として送出されます。
サンプルでは、クライアントの作成で作成した client を使います。app_id はあなたのアプリの ID で、client.account.me() で一覧できます。
SquareCloudAPIError
SquareCloudAPIError は Exception のサブクラスです。
str(error) は <METHOD> <path>: HTTP <status> <CODE>: <message> です。ステータスが 0 の場合は HTTP <status> が、メッセージが空の場合は : <message> が省かれます。
次の 2 つの失敗はラップされません:
- 空のキーや空白だけの API キーは、クライアントのコンストラクタで
ValueErrorを送出します。 - ローカルファイルの問題は
OSErrorを送出します: 開けないアップロードパス、アップロード中に読み取れなくなったファイル、書き込めないdownload_snapshotの保存先。
SDK のコード
コードは文字列
code はプレーンな str で、SDK にはコードの列挙型はありません。SquareCloudAPIError の docstring に既知の API コードがすべて列挙されています。RATE_LIMIT と RATE_LIMIT_EXCEEDED も非推奨として残っていますが、API は現在どちらの場合も RATE_LIMITED を返します。
API コードの一覧は増えていきます。不明なコードは HTTP ステータスで処理してください:
API のエラーコード
その他のコードはすべて API から返されます。API エラーリファレンスには各コードの HTTP ステータス、意味、対処法が掲載されており、SDK の各ページにはそのメソッドがよく返すコードを掲載しています。どの呼び出しでも、401ACCESS_DENIED (不正なキー)、403 MISSING_SCOPE または RESOURCE_NOT_ALLOWED (キーの制限)、429 (レート制限を参照)、503 DATABASE_UNAVAILABLE が返ることがあります。
ai.chat() のエラーは、代わりに小文字の OpenAI コード (access_denied、rate_limit_exceeded、server_overloaded など) を使います。AI を参照してください。
リトライ
SDK は安全に繰り返せるものだけを、最大max_retries 回 (デフォルトは 2 なので、最大 3 回の試行) リトライします:
次のものは決してリトライしません:
TIMEOUT- すべての 429:
RATE_LIMITEDは約 30 分のブロックである可能性があり、KEEP_CALMもリトライされません - その他の 5xx
- AI のエラー
DATABASE_UNAVAILABLE は変更がすでに適用された後に返されることがあるため、SDK は GET 以外ではリトライしません。必要であれば、冪等な変更は自分でリトライしてください。
リトライ n 回目 (0 から開始) の前の待機時間は min(8 s, 500 ms · 2^n) · U(0.5, 1) です。50%〜100% のジッターを伴う指数バックオフです。リトライを無効にするには max_retries=0 を設定します。
タイムアウト
timeout (30 秒) はリクエスト全体ではなく、ソケット操作ごと (接続と、各読み取り・書き込み) に適用されます。120 秒の下限がある呼び出しとタイムアウトのない呼び出しについては、タイムアウトを参照してください。タイムアウトはステータス 0 の TIMEOUT を送出し、リトライされることはありません。
レート制限
すべてのアカウントには、プランによって決まる 60 秒あたりのリクエスト数の制限があり (値)、一部のルートには独自の制限があります:- 429
RATE_LIMITED: アカウントまたは API キーがリクエストの上限を超えると、約 30 分ブロックされます。無効なキーを送り続ける IP も短時間ブロックされます。ネットワーク系 endpoint とaccount.snapshotsの制限でもあります。 - 429
KEEP_CALM: 短時間に 1 つのルートへの呼び出しが多すぎる。
次のステップ
API エラーリファレンス
すべてのエラーコードと、その意味と対処法。
制限と制約
各プランのリクエスト制限。

