信頼できる client の作り方

Idempotency

create / submit 系 request には visible ASCII、最大255 byteの Idempotency-Key を付けます。同じ key と同じ request は同じ論理 resource または Run へ収束します。endpoint、API version、主体が異なる操作で key を共有しないでください。

Pagination

list operation は opaque な page_token を使います。token の内容を解析・生成せず、response の next_page_token をそのまま次の request へ渡します。filter、sort、ContentSpace を変更した request へ古い token を再利用しません。

Error

公開 error は安全な code、日本語の message、requestId を返します。provider code、内部 gRPC message、credential、namespace の存在は公開されません。

Status	意味	client の基本動作
`400`	request が不正	request を修正する
`401`	認証できない	key を確認し、繰り返し再送しない
`404`	resource が見えない	ID と権限を同一扱いで確認する
`409`	前提条件を満たさない	indexing と active route を確認し、部分結果として扱わない
`429`	rate limit / quota	`Retry-After` に従う
`500`	予期しない失敗	request ID を保持し、制限付きで再試行する
`503`	provider、credential、検索資源の一時障害	backoff して再試行する

Backoff

再試行可能な応答だけを exponential backoff と jitter で再送します。最大回数と全体 timeout を設け、 terminal な Run を再び submit する代わりに状態を取得してください。