Skip to main content
API とネットワークのあらゆる失敗は、1 つの例外 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 の各ページにはそのメソッドがよく返すコードを掲載しています。どの呼び出しでも、401 ACCESS_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 のエラー
503 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 つのルートへの呼び出しが多すぎる。
SDK は 429 を決してリトライしません。ペースを落とし、しばらく待ってから再試行してください。

次のステップ

API エラーリファレンス

すべてのエラーコードと、その意味と対処法。

制限と制約

各プランのリクエスト制限。