*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 の各ページにはそのメソッドがよく返すコードを掲載しています。どの呼び出しでも、401ACCESS_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 のエラー。
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 つのルートへの呼び出しが多すぎる。
次のステップ
API エラーリファレンス
すべてのエラーコードと、その意味と対処法。
制限と制約
各プランのリクエスト制限。

