はじめに

hkob の雑記録の第537回目(連続113日目)は、Developer ChangeLog の 6/16 版を解説します。

Workspace-level rate limits

6/16 の Changelog には以下のように記載されていました。

Notion API では、既存の接続ごとの制限に加えて、ワークスペースごとのレート制限が適用されるようになりました。この制限はワークスペース内のすべての接続で共有され、ワークスペースのプランに応じてスケールされます。そのため、単一の接続が接続ごとの制限内に収まっていても、リクエストがレート制限される場合があります。他のレート制限と同様に、HTTP 429 レスポンスの Retry-After ヘッダーに従ってください。Request limits を参照してください。

これまでは既存の接続ごとの制限だけでした。ただし、複数のメンバーが MCP などを経由して API を利用するようになってきたので、ワークスペース全体としてのレート制限も適用されるようになったそうです。詳しくは Request limits に書かれているそうなので、そちらも確認してみます。

レート制限

Notion API では、2 種類のレート制限が適用されます。

接続ごと — 平均で 1 秒あたり 3 リクエストです。平均を超える一時的なバーストは一部許可されます。

ワークスペースごと — ワークスペース内のすべての接続で共有され、ワークスペースのプランに応じてスケールされます。

いずれかの制限を超えたリクエストは、"rate_limited" エラーコードと HTTP 429 レスポンスを返します。additional_data.rate_limit_reason には、どちらの制限を超えたかが示されます。たとえば、public_api_request_rate_limit や public_api_space_request_rate_limit です。接続は、HTTP 429 および 529 レスポンスを処理し、レスポンスの Retry-After ヘッダー値に従うことで、変動するレート制限に対応する必要があります。この値は、待機すべき秒数を 10 進数の整数で示します。529 は "service_overload" コードを伴い、Notion が一時的に過負荷であることを意味します。これも同じ方法で処理してください。この最小時間だけ待ってから送信したリクエストは、通常はそれ以上レート制限されません。別の方法として、今後のリクエスト速度をバックオフする、または低下させることで、レート制限に対応できます。一般的な実装方法は、保留中のリクエスト用に 1 つまたは複数のキューを用意し、Notion が HTTP 429 または 529 を返さない限り、そのキューからリクエストを送信して処理することです。

レート制限は変更される場合があります

Notion は今後、需要と信頼性のバランスを取るために、レート制限を調整する予定です。

特にワークスペースの制限については数値的には示されていないようです。ただし、もし制限に引っ掛かったら、返却されたエラーに待機すべき秒数が書かれているようですす。この時間以降まった場合には、それ以上レート制限されないとのことです。エラーコードが429 または 529 だった場合には、返り値も確認する必要があるようです。