Skip to main content
API、ネットワーク、ローカルのすべての失敗は、1 つの型 *squarecloud.APIError で表されます。errors.As で確認してください。 以下の短いスニペットは、サンプルの実行のプログラムの中で動作します。1 つずつ main に貼り付けて goimports を実行してください。

APIError

Unwrap() は、NETWORK_ERROR、TIMEOUT、無効な JSON の場合はその原因 (トランスポート、デコード、または context のエラー) を返し、それ以外では nil を返します。Error() は squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> を出力します。ステータスが 0 の場合は HTTP <status> が、メッセージが空の場合は : <message> が省かれます。このテキストではなく、フィールドで判定してください。

キャンセルされた context と期限切れの context

ctx がキャンセルされた呼び出しは NETWORK_ERROR の *APIError を返し、期限を過ぎた呼び出しは TIMEOUT を返します。どちらもステータスは 0 です。これらは context のエラーにアンラップされます:
いくつかの失敗は *APIError ではありません:
  • Realtime.Next は、その ctx が終了すると素の ctx.Err() を返し、ストリームが正常に終了すると io.EOF を返します。
  • 呼び出し側の問題は通常のエラーです: nil のアップロードリーダー、解析できない snapshot URL またはベース URL、encoding/json でエンコードできない入力、そして DownloadSnapshot に渡した io.Writer のエラー。

SDK のコード

Code* 定数

Code は通常の string です。パッケージには、公開されている API コードごとに、Go のスタイルで名付けられた定数が 1 つずつあり (APP_NOT_FOUND に対する CodeAppNotFound、CodeInvalidID、CodeDNSFailed など)、さらに上記の SDK 独自のコードもあります。CodeRateLimit (RATE_LIMIT) と CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) は非推奨としてエクスポートされたままですが、API は現在どちらの場合も RATE_LIMITED (CodeRateLimited) を返します。 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 など) を使い、Code にはそれがそのまま入ります。AI を参照してください。

リトライ

SDK は安全に繰り返せるものだけを、最大 WithMaxRetries 回 (デフォルトは 2 なので、最大 3 回の試行) リトライします: 次のものは決してリトライしません:
  • TIMEOUT;
  • すべての 429: RATE_LIMITED は約 30 分のブロックである可能性があり、KEEP_CALM もリトライされません;
  • その他の 5xx;
  • AI のエラー。
503 DATABASE_UNAVAILABLE は変更がすでに適用された後に返されることがあるため、SDK は GET 以外ではリトライしません。必要であれば、冪等な変更は自分でリトライしてください。アップロードがリトライされるのは、ボディを再送できる場合だけです。つまり、*os.File のようにサイズがわかっている io.ReaderAt です (Commit とアップロードを参照)。 リトライ n 回目 (0 から開始) の前の待機時間は min(8 s, 500 ms · 2^n) · U(0.5, 1) です。50%〜100% のジッターを伴う指数バックオフです。リトライを無効にするには WithMaxRetries(0) を設定します。

タイムアウト

WithTimeout (30 秒) は ctx に期限がない場合にのみ適用され、1 つの期限がリトライとバックオフの待機時間を含む呼び出し全体を対象とします。2 分の下限がある呼び出しと、デフォルトの期限がない呼び出しについては、タイムアウトを参照してください。期限を過ぎるとステータス 0 の TIMEOUT が返され、リトライされることはなく、context.DeadlineExceeded にアンラップされます。

レート制限

すべてのアカウントには、プランによって決まる 60 秒あたりのリクエスト数の制限があり (値)、一部のルートには独自の制限があります:
  • 429 RATE_LIMITED: アカウントまたは API キーがリクエストの上限を超えると、約 30 分ブロックされます。無効なキーを送り続ける IP も短時間ブロックされます。ネットワーク系 endpoint と Account.Snapshots の制限でもあります。
  • 429 KEEP_CALM: 短時間に 1 つのルートへの呼び出しが多すぎる。
SDK は 429 を決してリトライしません。ペースを落とし、しばらく待ってから再試行してください。

次のステップ

API エラーリファレンス

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

制限と制約

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