技術通知

為了協助維持系統穩定性並改善效能，Adobe Acrobat Sign 正在為 GET API 端點引入輪詢臨界值。 此原則限制用戶端應用程式對 Acrobat Sign 服務進行相同 API 呼叫的頻率。

高頻率輪詢會對後端系統造成不必要的負載，這可能會使效能下降，以及使回應時間變慢。 建議 API 開發人員使用 webhooks 來取得近乎即時的更新，而非重複輪詢。

變更的內容

輪詢原則會套用至相同呼叫的所有 GET API 端點。

系統將限制同一個有效使用者向 Acrobat Sign 發出相同 API 呼叫的頻率。 當同一個有效使用者進行相同呼叫的頻率超過適用輪詢臨界值允許的頻率時，會傳回錯誤。

例如，對相同端點針對相同合約或資料庫文件的重複請求會被視為相同呼叫。 針對不同合約或資料庫文件的請求會被視為不同呼叫，因為每個物件代表不同的請求目標。

受影響端點的範例

狀態擷取

• GET /agreements/{agreementId} — 檢索合約的目前狀態。
• GET /agreements/{agreementId}/documents/{documentId} — 檢索合約中文件的檔案串流。

清單、事件和資料庫文件

• GET /agreements — 檢索使用者的合約。
• GET /agreements/{agreementId}/events — 檢索合約的事件資訊。
• GET /libraryDocuments — 檢索使用者的資料庫文件。
• GET /libraryDocuments/{libraryDocumentId} — 檢索特定資料庫文件的資訊。

輪詢原則詳細資訊

最小物件輪詢間隔(MOPI)定義相同有效使用者可以對 Adobe Acrobat Sign 服務進行相同 GET API 請求的頻率。

預設 MOPI 會因服務層級而異：

• GLOBAL、ENTERPRISE 和 DEVELOPER 層級：每分鐘可進行三次相同呼叫。
• 所有其他層級：每三分鐘間隔三次相同呼叫。

如果同一個有效使用者進行相同 GET 請求的頻率高於層級允許的頻率，Acrobat Sign 會傳回標頭為 Retry-After 的「429 請求過多」回應。

當相同的有效使用者在適用的輪詢間隔內以相同的要求路徑和頁首進行相同的 GET 要求時，該要求會被視為相同要求。

ETag 處理

應用程式可以繼續針對支援條件式 GET 要求的端點使用 ETag 和 If-None-Match 頁首。

針對輪詢臨界值允許範圍內的條件式 GET 要求，當資源未變更時，Acrobat Sign 可能會回傳 304 Not Modified。

超過輪詢臨界值後，即使請求含有 If-None-Match 標頭，Acrobat Sign 仍會傳回標頭為 Retry-After 的「429 請求過多」。

必須採取的行動

如果您的應用程式需要近乎即時的更新，請使用 Webhook，而不是輪詢。 Webhooks 提供更有效率且可擴充的方式來接收即時更新。

如果無法實作 Webhook，應用程式應使用客戶端快取來儲存和重複使用 API 回應。

• 當收到「304 未修改」回應時，請使用快取的資料，而不是進行其他 API 呼叫。
• 當收到「429 請求過多」回應時，僅限在 Retry-After 標頭中提供的秒數後重試 API 呼叫。

資源

• 處理 429 回應：https://developer.adobe.com/acrobat-sign/docs/overview/developer_guide/apiusage#handling-rate-limiting-http-429
• API 輪詢臨界值：https://developer.adobe.com/acrobat-sign/docs/overview/developer_guide/apiusage#get-endpoints

時間軸

更新的 MOPI 臨界值已在正式環境中使用。

• 更新的 ETag 節流行為已包含在 17.1.1 版本中。 在此變更後，Acrobat Sign 會針對節流要求回傳 429 Too Many Requests，包括含有 If-None-Match 標頭的條件式 GET 要求。
• 在 2026 年 2 月 11 日，沙箱環境中新帳戶的輪詢原則設定為 ENFORCED。
• 在 2026 年 4 月 5 日，生產環境中新帳戶的輪詢原則設定為 ENFORCED。

如果您需要協助或有任何問題，請聯絡您的客戶成功經理。