錯誤

外層格式

一切都以 detail 為鍵，三種形狀之一：

1. 字串 — {"detail": "<sanitized message>"}（EdgeWorkerHttpErrorResponse）。除 422 外每個文件化 ≥400 狀態的預設。
2. 清單 — {"detail": [{"loc": [...], "msg": "...", "type": "..."}]}（EdgeWorkerValidationErrorResponse）。FastAPI 的 422 以及提交路由手工產生的 422（loc: ["body", "project"]，機器可讀的代碼放在 type），還有操作設定與部署路由手工產生的 422。
3. 帶代碼物件 — {"detail": {"code": "...", "message": "..."}}。不再只出現在 POST /worker/versions 的 503：存取政策、執行期設定、操作設定、機密、部署、OpenAPI、原始碼下載與服務帳號路由的 409、413、503 也會帶代碼 detail。在每條控制路由上都要把 detail 當成無標記 union string | {code, message}，當它是物件時依 detail.code 分支。產生的 OpenAPI 對此描述不足：多數這類回應仍被標成字串形狀（只有機密路由、提交路由與原始碼下載路由宣告了 union）。

dispatcher 與 runtime 的錯誤（公開／dispatch 通道）用另一種外層：{"code", "message", "requestId"} 加 cache-control: no-store。

狀態碼語意

403 目錄（精確字串）

Edge Workers require TeamSync JWT authentication（防禦性檢查，見下）· Insufficient permissions.（管理者與公司路由）· Service accounts cannot invoke Edge Workers · A live Edge Worker user is required · A department identity is required for Edge Workers · A live department identity is required for Edge Workers · A company identity is required for Edge Workers

• Edge Workers require TeamSync JWT authentication 是一道防禦性檢查，已發佈的只收 JWT 依賴不會走到它：沒有有效 Bearer JWT 的請求（包括 x-api-key 金鑰）會先得到 418。見驗證。
• 服務帳號拒絕與有效使用者重驗，適用於每條部門範圍的路由（成員與管理者），包括 /starters 與部門服務帳號路由。公司路由（/company/departments/**）不執行服務帳號拒絕。服務帳號是角色 0，所以在管理者路由上通常會先遇到 Insufficient permissions.。
• A live Edge Worker user is required：重新讀取的使用者列不存在、已刪除、已停用、未驗證或已過期。
• 服務帳號路由另有 A live manager identity is required（操作中的管理者列已不存在），以及防禦性的共用角色階層檢查：403 Insufficient permissions. (Different Company)、400 Cannot modify yourself.（目標就是呼叫者本人）與 403 Insufficient permissions.（目標的角色並未嚴格低於操作中的管理者）。
• 公開與 dispatch 通道有自己的 403 代碼（access_denied、worker_retired、operation_settings_pending）：見本頁最後的 dispatcher 與 runtime 表。

409 目錄（精確字串）

純字串：Department Worker must be deployed and active · Access policy revision is stale · Runtime config revision is stale · Operation-settings revision is stale · Worker secret mutation is stale · Operation settings are pending（設定尚未 reconciled 的 Worker 撤銷操作金鑰）· a Worker already exists for this department · Worker revision changed; refresh before deploying · Worker version was superseded; V2 rollback is not supported · uncertain deployment requires company reconciliation · Worker version cannot deploy from state '<state>' · Worker deployment sequence is exhausted · deployment intent already exists · Repair parameters do not match the original request · Worker revision is stale; refresh department state · Deployment revision is stale; refresh department state · Only an uncertain deployment can be reconciled · Only an uncertain deployment version can be reconciled · Service account name is unavailable · Service-account credential delivery is stale · operation-settings digest differs from the existing deployment（部署競態）· worker_migration_in_progress（平台搬移 Worker 期間的部署，但搬移短暫暫停的期間除外，那時部署回 Operation-settings revision is stale，已持有逐操作設定的 Worker（或帶有 operation_settings 的請求）也除外，它得到 503 Department Worker control change is unavailable；搬移 Worker）· Worker deployment target cannot be verified（競態後備，對應下面帶代碼的 worker_serving_target_unavailable）· Worker deployment target is unavailable（同樣的競態，或 Worker 第一次部署時，此環境所設定的預設位置無法使用：屬於平台設定問題）

a deployment is already active for this department Worker 現在只是部署 outbox 內的競態後備：另一張票證仍在進行時再送部署請求，通常會拿到下面帶代碼的 deployment_in_progress。曾比對舊字串的用戶端必須改讀 detail.code。

帶代碼的 409（{"code", "message"}）：

僅地端：部署或修復在 resync epoch 進行中回 409，detail 為純字串 edge_workers_maintenance，還原保護（restore hold）開啟時為 edge_workers_restore_pending（雲端永遠不會送出這兩個）。見地端 Edge Workers。

413 目錄

POST /worker/deployments 可帶選用的 operation_settings 物件，但仍沒有路由層級的 body 上限。

422 目錄

503 目錄（精確字串）

純字串：Deployed department Worker release is unavailable · Department Worker runtime config is unavailable · Department Worker access policy is unavailable · Department Worker operation settings are unavailable · Department Worker operation key is unavailable · Department Worker secrets are unavailable · Department Worker service-account credentials are unavailable · Operation-settings mutation lock is unavailable · Department Worker public URL is unavailable · Department Worker control change is unavailable · Department Worker serving target is unavailable（Worker 所記錄的服務位置不一致，或其 release 在此期間改變；多處都會丟出它，其中包括存取政策與操作設定路由、執行期設定的讀取、機密清單與機密寫入、OpenAPI 文件、部署中的操作設定暫存，以及 invoke 路由；其他有稽核的變更則改回 409 worker_serving_target_unavailable）· Department Worker gateway URL is not configured · Deployed department Worker contract is unavailable · Department Worker gateway is unavailable · Deployment dispatch is unavailable · Edge Worker provider is not configured（提交、部署與修復）· Edge Worker artifact storage is unavailable · Edge Worker artifact compensation is unavailable

帶代碼的 503（{"code", "message"}）：

機密值送出後的 503 並不代表有沒有寫入：請列出機密並比對 updated_at，或再寫一次。

服務帳號路由

七條部門路由與其公司鏡像（見服務帳號）在上述關卡之外另有：404 Service account not found（不存在、已刪除、屬於其他部門、其他公司，或是人類使用者的 id：同一種形狀）、404 Department not found（公司鏡像路徑，或建立時的競態）、409 Service account name is unavailable（該 UTC 秒內的 99 個名稱全被占用）、422 Invalid cursor 與 add and remove must be disjoint。憑證重設在設定鎖被持有時回 409 deployment_in_progress，鎖的儲存無法使用時回 503 Operation-settings mutation lock is unavailable；所有憑證交付問題都是 200 加上 delivery: "failed"，絕不是錯誤狀態。刪除即使 Worker 清理失敗或被延後，也回 200。

範本與原始碼下載

閘道 invoke 錯誤

部署票證 error_code 值

dispatch_not_accepted · outbox_payload_invalid · artifact_integrity_failed · deployment_retryable_internal · deployment_internal_error · deployment_reconciliation_unavailable · retry_exhausted · retry_transport_unavailable · provider_bundle_mismatch · provider_settlement_lost · cloudflare_upload_uncertain · cloudflare_response_invalid · cloudflare_upload_rejected · cloudflare_rate_limited · cloudflare_reconcile_unavailable · cloudflare_reconcile_invalid · cloudflare_reconcile_rejected · cloudflare_config_invalid · script_name_invalid · bundle_digest_invalid · compatibility_date_invalid · artifact_unavailable · worker_readiness_timeout（uncertain：回讀吻合，但就緒輪詢在一次失敗的 access_policy.get 探測後用盡了 600 秒截止點 — 後端 5.22.0 之前為 60 秒）· department_deleted · edge_workers_provider_invalid · legacy_serving_target_unavailable · deployment_target_unavailable · deployment_target_release_changed

• department_deleted — failed：部署還在排隊時，部門已被刪除。在取得租約之後、上傳任何東西之前檢查，所以已刪除部門的 Worker 不會被復活；修訂版的 error_message 維持 deployment failed，Worker 狀態回到 active（或 draft）。
• edge_workers_provider_invalid — failed（若修訂版已是 deploying，也就是 reconcile，則為 uncertain）：EDGE_WORKERS_PROVIDER 不是可用的 provider 值。
• legacy_serving_target_unavailable — failed：票證是由早於 5.22.0 的後端排入、在升級之後才被處理（新 Worker 的第一次部署也包括在內），而無法證明它原本的 Worker 位置就是目前服務該 Worker 的位置。這次嘗試沒有呼叫 provider，Worker 狀態回到 active（或 draft）。請再部署一次；若被 409 worker_serving_target_unavailable 拒絕，平台維運者必須先驗證該 Worker 的位置。
• deployment_target_unavailable 與 deployment_target_release_changed — failed（reconcile 時為 uncertain）：部署任務無法依票證上記錄的服務位置建出它的 provider 用戶端，原因是該位置不是此環境會執行的位置，或是記錄的 release digest 與修訂版的不同。這次嘗試沒有呼叫 provider（reconcile 時，較早的嘗試可能已經上傳過）。
• 在 v2.6 以上的 release 上部署 builder 政策早於 v2.6 的 release，會先清除所有 Worker 機密。若清除未被確認，或 Worker 或其現行 release 在期間改變，票證以 artifact_integrity_failed 結算為 failed；清除期間的閘道錯誤則以 deployment_internal_error 結算為 failed。此時尚未上傳任何東西。

僅地端（EDGE_WORKERS_PROVIDER=onprem；Worker 主機用戶端的代碼，見地端 Edge Workers）：

控制面稽核通道另有：control_receipt_not_found · control_receipt_invalid · control_receipt_unavailable · control_audit_payload_invalid · control_receipt_ack_failed · revision_conflict · provider_outcome_unknown · legacy_serving_target_unavailable（自後端 5.22.0 起：不帶已記錄之服務位置的控制回執 — 在該版本之前排入，或為由舊有位置服務的 Worker 排入 — 其所在的 Worker 位置無法對應到 Worker 目前的位置；該意圖結算為 failed，或其確認停止重試）；Durable Object 的帶代碼拒絕會以拒絕本身的代碼把意圖結算為 failed（worker_wide_key_legacy_only、secret_limit_exceeded、secret_size_exceeded、service_account_limit_exceeded、operation_not_found）。Worker 已退役的控制意圖或回執不會再重試：其 outbox 列結束為 cancelled，或以 worker_retired 停止重試，且不寫稽核列。清理通道：cleanup_payload_invalid · artifact_cleanup_failed · submission_not_committed。部署回收會把 Worker 列已不存在（公司硬刪除）的排隊部署，以 worker_deleted 結算為 failed。

builder 拒絕代碼

透過 HTTP，每個不可重試的 builder 拒絕看起來都一樣： 422 {"detail": [{"loc": ["body", "project"], "msg": "project failed the locked Worker build policy", "type": "project_invalid"}]}。下面列的精確代碼不會出現在回應中。空的壓縮檔是 422 project_archive_required，超過 2 MiB 的是 413，兩者都在 builder 執行之前就回應。代碼只會在本機印出：teamsync-worker validate|pack|submit|dev|generate 結尾會印 teamsync_worker_failed:authoritative builder rejected project: <code>。用同一個後端提供的 CLI（GET /starters/cli.tgz）執行 validate，就能看到上傳為何被拒。

可重試的 builder 失敗是 503 並帶代碼 body：internal_build_error 與 approved_dependency_unavailable 呈現為 builder_unavailable；無法解析或不一致的 builder 回答是 builder_invalid_output。建置成功後後端會重新驗證 manifest：這裡失敗是 422 manifest_v2_invalid。

來自 edge/department-workers/scripts/build.mjs 超過 100 個代碼，分組：

• 壓縮檔：project_archive_invalid、project_archive_not_deterministic、project_archive_duplicate_path、project_archive_path_invalid、project_archive_non_regular_file、project_archive_limits_exceeded、project_file_size_invalid、project_file_type_forbidden、project_prebuilt_artifact_forbidden、project_required_file_missing、project_identity_mismatch、project_archive_file_invalid
• Manifest：manifest_version_unsupported、manifest_invalid、manifest_encoding_invalid、manifest_unknown_field、manifest_module_invalid/_unknown_field、manifest_language_invalid、manifest_entrypoint_invalid/_missing/_language_mismatch、manifest_compatibility_date_invalid、manifest_api_invalid/_unknown_field、manifest_tags_invalid、manifest_tag_*（duplicate、invalid、unknown_field、unreferenced）、manifest_operations_invalid、manifest_operation_invalid、manifest_operation_*（id_invalid、summary_invalid、description_invalid、tag_unknown、tags_invalid、unknown_field）、manifest_method_invalid、manifest_route_invalid/_reserved/_ambiguous、manifest_parameter_*（duplicate、invalid、header_reserved、unknown_field）、manifest_path_parameter_invalid、manifest_query_parameter_invalid、manifest_request_body_invalid/_unknown_field、manifest_responses_invalid、manifest_response_invalid/_body_forbidden/_unknown_field、manifest_schema_invalid/_unknown_field、manifest_schemas_invalid、manifest_number_invalid、manifest_json_invalid、manifest_unicode_invalid、manifest_file_invalid
• Example：manifest_example_json_invalid、_limits_exceeded、_nul_forbidden、_number_invalid、_integer_unsafe、_schema_invalid、_schema_mismatch、_secret_forbidden、_secret_field_forbidden
• 靜態資料：static_data_encoding_invalid、_file_size_invalid、_integer_unsafe、_json_invalid、_json_limits_exceeded、_limits_exceeded、_nul_forbidden、_secret_forbidden、_secret_field_forbidden
• 套件：package_json_invalid/_field_forbidden、package_dependencies_invalid、package_dependency_not_approved、package_lock_invalid/_field_forbidden/_graph_invalid、tsconfig_invalid/_field_forbidden
• 原始碼：source_encoding_invalid、source_import_forbidden/_not_found/_ambiguous、source_reference_forbidden、source_dynamic_code_forbidden、source_dynamic_import_forbidden、source_dependency_not_declared/_not_approved、source_build_failed
• Bundle：bundle_size_invalid、bundle_dynamic_code_forbidden、bundle_policy_invalid
• builder 內部（以 503 builder_unavailable 呈現、可重試）：internal_build_error、approved_dependency_unavailable；builder 自己的參數與輸出路徑檢查另有 arguments_invalid、output_already_exists、output_path_invalid

dispatcher 與 runtime 錯誤代碼（{code, message, requestId} 外層）

worker_not_found 來自兩種情況：dispatcher 在所有綁定位置都找不到該 script（或被釘選的位置沒有它），以及退役 Worker 的墓碑 — 墓碑對每個路徑都以同一種外層回 404。Worker 自己丟出訊息為 Worker not found 的錯誤不是 404：而是 502 worker_execution_failed。正在被刪除的部門，其呼叫者可能短暫看到 403 worker_retired，之後從墓碑看到 404 worker_not_found。

地端主機用同一個外層回答：503 worker_unavailable（Worker 正在啟動或切換，且超過了暫留請求的上限或 EDGE_HOST_HOLD_MS，或它被隔離、或因超過儲存預算而被停止）、502 worker_execution_failed（Worker 行程連不上）、404 worker_not_found（已退役、未知或從未啟用）、以及呼叫超過牆鐘預算（EDGE_HOST_INVOCATION_TIMEOUT_MS，預設 30 秒；沒有逐次呼叫的 CPU 上限）時的 429 worker_limit_exceeded。地端的子請求池是在 Worker 自己的 fetch() 內丟出例外：沒被捕捉時就是 500 worker_execution_failed。見限制一覽。

沒有 Outbound Worker：部門 Worker 自己的 fetch() 永遠不會被攔截或改寫，所以在雲端 runtime 上，平台會發出的唯一網路相關錯誤是呼叫超過子請求或 CPU 上限時的 429 worker_limit_exceeded — 預設 500／50 ms：簽章通道用斷言的 limits claim，公開通道用 dispatcher 的 EDGE_WORKER_SUBREQUESTS／EDGE_WORKER_CPU_MS（限制一覽）。目的地回什麼，handler 就看到什麼。原始 TCP connect() 在兩種 runtime 上都根本到不了 runtime：匯入 cloudflare:sockets 會在建置時以 source_import_forbidden 被拒絕。

回應 header x-teamsync-request-id 攜帶一個貫穿 dispatcher → runtime → 用戶端的關聯 UUID；兩側日誌都是以同一 id 為鍵的結構化 JSON，永不包含 claims、header、body 或金鑰材料。Worker 產生的回應也可能帶有 x-teamsync-serving-namespace 與 x-teamsync-routing-epoch：這是 dispatcher 設定（並覆寫）的平台診斷用 header，Worker 程式碼無法設定，用戶端不應解析或依賴它們。