REST APIのエラーとページ分割に対処する

信頼できるクライアントは、ページの状態、認証の失敗、権限による拒否、競合、一時的な制限を別々の結果として扱います。dosyaのファイル一覧では継続トークンを使用しません。

応答の形式

成功時のJSONには通常ok:trueが含まれます。失敗時は通常{ "ok":false, "error":"…" }を使用します。folder_lockedなどの構造化エラーにはフィールドが追加されることがあります。機密情報を除いたログにHTTPステータスとエラー本文全体を保存してください。

GET /api/filesはpageとper_pageを使用します。応答のpaginationオブジェクトにはpage、per_page、total_files、total_pagesが含まれます。

手順

1. ワークスペース、フォルダー、フィルター、並べ替え、per_pageを固定して1ページ目をリクエストし、処理中はそれらのクエリ値を変えないでください。
2. 各ファイルをidで処理し、現在のページ番号を保存して、同じ応答からpagination.total_pagesを読み取ってください。
3. 処理したページがtotal_pagesと等しくなるまでpageを増やしてください。カーソル、継続情報、next_pageフィールドは探さないでください。
4. 成功以外の応答では、Bearerキーを保存せず、ステータス、error、Retry-After、レート制限ヘッダーを記録してください。
5. 429と再試行可能な503はRetry-Afterの後に再試行してください。GET、HEAD、または文書化されたマルチパートのパート再試行は繰り返せますが、変更操作を再実行する前に状態を確認してください。
6. 最後に処理済みファイルIDを照合し、未解決の失敗を残したままページ全体を完了としないでください。

ステータスと待機時間の規則

401 Invalid or expired API keyでは認証情報や有効期限を確認してください。一時的な認証情報の照会エラーでは、代わりにRetry-After: 5を伴う503 Service temporarily unavailableが返ります。403はスコープ、利用先、ワークスペースの固定先、ロール、ロック、その他のアクセス規則によって発生します。404は非表示または範囲制限されたリソースを意図的に隠す場合があります。409は状態の競合を示します。429の本文にはToo many requestsが含まれます。

ほとんどのAPI応答にはX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが含まれます。認証済みファイル一覧のポーリングにはユーザーあたり1分間に600回の枠が適用され、60秒間に600回のIP制限も通過する必要があります。一般的なREST通信とアップロードの初期化はユーザーあたり1分間に300回です。プランまたはキーごとの上限がそれより低い場合は、そちらが先に適用されます。

ファイルのページ分割はオフセット方式のため、走査中の追加や削除によって後続ページの行がずれることがあります。安定したエクスポートには並行する変更を停止し、それができない場合はファイルIDで重複を除いてください。

期待される結果

処理中の各ページ番号は最大1回処理され、すべてのファイルIDが照合されます。再試行可能な応答ではサーバーが指定した時間だけ待機し、恒久的な拒否は対処できる状態で残ります。

関連ガイド

• REST APIクイックスタート
• APIキーのスコープ