From fbd2d42b0c6a65556d49c48b1cacc623dd558523 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 13:03:24 -0400 Subject: [PATCH 1/8] Add Craft Cloud diagnostics guidance --- docs/.vuepress/sets/craft-cloud.js | 1 + docs/cloud/diagnostics.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 docs/cloud/diagnostics.md diff --git a/docs/.vuepress/sets/craft-cloud.js b/docs/.vuepress/sets/craft-cloud.js index ab193c5ea..7e02159d4 100644 --- a/docs/.vuepress/sets/craft-cloud.js +++ b/docs/.vuepress/sets/craft-cloud.js @@ -81,6 +81,7 @@ module.exports = { title: "Help", collapsable: false, children: [ + "diagnostics", "faq", "troubleshooting", "security", diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md new file mode 100644 index 000000000..c41d71ac7 --- /dev/null +++ b/docs/cloud/diagnostics.md @@ -0,0 +1,26 @@ +--- +description: Safely collect useful details when diagnosing failed requests to Craft Cloud. +--- + +# Diagnostics + +When a request to your Craft Cloud environment fails, log the following +response details before handling the error: + +- HTTP status code +- `x-gateway-http-signature`, if present +- `Retry-After`, if present + +The `x-gateway-http-signature` header reports whether Craft Cloud detected and +validated [request signing](request-signing.md). A value of `verified` means +validation succeeded; `unverified` means signing was detected but validation +failed. + +The `Retry-After` header indicates how long the client should wait before +retrying. Preserve the returned value in logs and honor it when scheduling a +retry. + +Log these fields individually from trusted server-side code. Never dump +complete request headers, environment variables, or credentials. In +particular, never log the Craft Cloud signing key, GraphQL tokens, or other +secrets. From 21892699aecec4d39fd57db54b0a8a65ca8e6c13 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 13:19:08 -0400 Subject: [PATCH 2/8] Document gateway flow diagnostics --- docs/cloud/diagnostics.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index c41d71ac7..db3d0688e 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -8,9 +8,15 @@ When a request to your Craft Cloud environment fails, log the following response details before handling the error: - HTTP status code +- `x-gateway-flow`, if present - `x-gateway-http-signature`, if present - `Retry-After`, if present +The `x-gateway-flow` header identifies how Craft Cloud produced the response. +For example, `/origin/fetch` means the gateway fetched the environment’s +origin, while `/origin/reject` means it rejected the request before contacting +the origin. + The `x-gateway-http-signature` header reports whether Craft Cloud detected and validated [request signing](request-signing.md). A value of `verified` means validation succeeded; `unverified` means signing was detected but validation From 387c3e192455d5ebc1bfe4a75c38be5d7a338cf7 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 13:29:00 -0400 Subject: [PATCH 3/8] Explain Cloud request failure diagnostics --- docs/cloud/diagnostics.md | 41 +++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index db3d0688e..6a6f1c624 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -4,10 +4,14 @@ description: Safely collect useful details when diagnosing failed requests to Cr # Diagnostics -When a request to your Craft Cloud environment fails, log the following -response details before handling the error: +When a request to your Craft Cloud environment fails, log the following details +before handling the error: +- Timestamp and timezone +- HTTP method, hostname, and path - HTTP status code +- `cf-ray`, if present +- `x-gateway-cf-ray`, if present - `x-gateway-flow`, if present - `x-gateway-http-signature`, if present - `Retry-After`, if present @@ -22,11 +26,36 @@ validated [request signing](request-signing.md). A value of `verified` means validation succeeded; `unverified` means signing was detected but validation failed. +The `cf-ray` and `x-gateway-cf-ray` headers identify the request at separate +Cloudflare layers. Log both when they are present so Craft support can +correlate the request. + The `Retry-After` header indicates how long the client should wait before retrying. Preserve the returned value in logs and honor it when scheduling a retry. -Log these fields individually from trusted server-side code. Never dump -complete request headers, environment variables, or credentials. In -particular, never log the Craft Cloud signing key, GraphQL tokens, or other -secrets. +## Interpreting Failures + +A status code describes the outcome, but not which layer produced it. Combine +it with `x-gateway-flow` and the other diagnostic headers: + +| Combination | Interpretation | +| --- | --- | +| Any `4xx` or `5xx` with `x-gateway-flow: /origin/fetch` | Your application returned the response. Inspect its logs and error handling. | +| `400` with `x-gateway-flow: /origin/reject` | The request body failed gateway validation. Fix the request rather than retrying it unchanged. | +| `401` with `x-gateway-http-signature: unverified` | A signature-protected gateway endpoint rejected an invalid or expired signature. Check the signing key, method, target URL, timestamp, and expiry before signing again. | +| `403` with `x-gateway-flow: /origin/reject` | A gateway request policy blocked the request before it reached your application. Do not retry it unchanged. | +| `404` with `x-gateway-flow: /` | The gateway could not match the hostname to a Craft Cloud environment. Check the requested hostname. | +| `413` with `x-gateway-flow: /origin/reject` | The request body was too large for the origin request path. Reduce its size. | +| `429` with `x-gateway-flow: /origin/reject` and `Retry-After` | The gateway rate limited the request before it reached your application. Honor `Retry-After`. A `verified` signature confirms signing worked, but does not bypass shared capacity limits. | +| `429` with `x-gateway-flow: /origin/fetch` | Your application returned the rate limit. Honor its `Retry-After` header, if present, and inspect application-level limits. | +| `500` with an `x-gateway-flow` value ending in `/error` | The gateway encountered an internal error. Retry only safe requests, and contact support if it persists. | +| `502` with `x-gateway-flow: /origin/fetch/error` | The gateway could not get a usable response from the origin after a connection or platform error. Contact support if it persists. | +| `503` with `x-gateway-flow: /origin/fetch/error` and `Retry-After` | Origin compute was temporarily throttled. Honor `Retry-After` before retrying a safe request. | +| `504` with `x-gateway-flow: /origin/fetch/error` | Origin work exceeded the [request duration limit](quotas.md#requests-responses). Reduce the work performed during the request. | +| Any `5xx` without `x-gateway-flow` | The failure may have occurred before the request reached the gateway. Preserve the Ray IDs and `Retry-After`, if present, when contacting support. | + +Log these fields individually from trusted server-side code. Do not log query +strings unless you have removed sensitive values. Never dump complete request +headers, environment variables, or credentials. In particular, never log the +Craft Cloud signing key, GraphQL tokens, or other secrets. From 3042b3e412c007ec27230e7629da91f3a2691af2 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 16:10:34 -0400 Subject: [PATCH 4/8] Lead with diagnostic headers --- docs/cloud/diagnostics.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index 6a6f1c624..8eade6640 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -4,17 +4,7 @@ description: Safely collect useful details when diagnosing failed requests to Cr # Diagnostics -When a request to your Craft Cloud environment fails, log the following details -before handling the error: - -- Timestamp and timezone -- HTTP method, hostname, and path -- HTTP status code -- `cf-ray`, if present -- `x-gateway-cf-ray`, if present -- `x-gateway-flow`, if present -- `x-gateway-http-signature`, if present -- `Retry-After`, if present +## Response Headers The `x-gateway-flow` header identifies how Craft Cloud produced the response. For example, `/origin/fetch` means the gateway fetched the environment’s From 3aab863a2596fc017fb7541985c86f8a09dfd561 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 16:19:15 -0400 Subject: [PATCH 5/8] Document Cloudflare response diagnostics --- docs/cloud/diagnostics.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index 8eade6640..95df3d4a5 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -16,13 +16,19 @@ validated [request signing](request-signing.md). A value of `verified` means validation succeeded; `unverified` means signing was detected but validation failed. -The `cf-ray` and `x-gateway-cf-ray` headers identify the request at separate -Cloudflare layers. Log both when they are present so Craft support can -correlate the request. - -The `Retry-After` header indicates how long the client should wait before -retrying. Preserve the returned value in logs and honor it when scheduling a -retry. +The `cf-ray` header identifies the request in Cloudflare, while +`cf-cache-status` describes how Cloudflare handled it in the cache. See +[Troubleshooting Static Caching](static-caching.md#troubleshooting) for common +cache statuses. + +### Cloudflare O2O + +When [Cloudflare O2O](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/) +routes a request through both a customer zone and Craft Cloud’s SaaS provider +zone, `cf-ray` and `cf-cache-status` describe the customer zone. +`x-gateway-cf-ray` and `x-gateway-cf-cache-status` provide the corresponding +Ray ID and cache status for the Craft Cloud zone. Preserve both sets when they +are present so Craft support can correlate the request. ## Interpreting Failures From 92dfab9332b5b6ff0875e875b4038f0e14498984 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 16:34:52 -0400 Subject: [PATCH 6/8] Split diagnostic status and headers --- docs/cloud/diagnostics.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index 95df3d4a5..7887b5d07 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -35,21 +35,21 @@ are present so Craft support can correlate the request. A status code describes the outcome, but not which layer produced it. Combine it with `x-gateway-flow` and the other diagnostic headers: -| Combination | Interpretation | -| --- | --- | -| Any `4xx` or `5xx` with `x-gateway-flow: /origin/fetch` | Your application returned the response. Inspect its logs and error handling. | -| `400` with `x-gateway-flow: /origin/reject` | The request body failed gateway validation. Fix the request rather than retrying it unchanged. | -| `401` with `x-gateway-http-signature: unverified` | A signature-protected gateway endpoint rejected an invalid or expired signature. Check the signing key, method, target URL, timestamp, and expiry before signing again. | -| `403` with `x-gateway-flow: /origin/reject` | A gateway request policy blocked the request before it reached your application. Do not retry it unchanged. | -| `404` with `x-gateway-flow: /` | The gateway could not match the hostname to a Craft Cloud environment. Check the requested hostname. | -| `413` with `x-gateway-flow: /origin/reject` | The request body was too large for the origin request path. Reduce its size. | -| `429` with `x-gateway-flow: /origin/reject` and `Retry-After` | The gateway rate limited the request before it reached your application. Honor `Retry-After`. A `verified` signature confirms signing worked, but does not bypass shared capacity limits. | -| `429` with `x-gateway-flow: /origin/fetch` | Your application returned the rate limit. Honor its `Retry-After` header, if present, and inspect application-level limits. | -| `500` with an `x-gateway-flow` value ending in `/error` | The gateway encountered an internal error. Retry only safe requests, and contact support if it persists. | -| `502` with `x-gateway-flow: /origin/fetch/error` | The gateway could not get a usable response from the origin after a connection or platform error. Contact support if it persists. | -| `503` with `x-gateway-flow: /origin/fetch/error` and `Retry-After` | Origin compute was temporarily throttled. Honor `Retry-After` before retrying a safe request. | -| `504` with `x-gateway-flow: /origin/fetch/error` | Origin work exceeded the [request duration limit](quotas.md#requests-responses). Reduce the work performed during the request. | -| Any `5xx` without `x-gateway-flow` | The failure may have occurred before the request reached the gateway. Preserve the Ray IDs and `Retry-After`, if present, when contacting support. | +| Status | Response Headers | Interpretation | +| --- | --- | --- | +| `4xx/5xx` | `x-gateway-flow: /origin/fetch` | Your application returned the response. Inspect its logs and error handling. | +| `400` | `x-gateway-flow: /origin/reject` | The request body failed gateway validation. Fix the request rather than retrying it unchanged. | +| `401` | `x-gateway-http-signature: unverified` | A signature-protected gateway endpoint rejected an invalid or expired signature. Check the signing key, method, target URL, timestamp, and expiry before signing again. | +| `403` | `x-gateway-flow: /origin/reject` | A gateway request policy blocked the request before it reached your application. Do not retry it unchanged. | +| `404` | `x-gateway-flow: /` | The gateway could not match the hostname to a Craft Cloud environment. Check the requested hostname. | +| `413` | `x-gateway-flow: /origin/reject` | The request body was too large for the origin request path. Reduce its size. | +| `429` | `x-gateway-flow: /origin/reject` and `Retry-After` | The gateway rate limited the request before it reached your application. Honor `Retry-After`. A `verified` signature confirms signing worked, but does not bypass shared capacity limits. | +| `429` | `x-gateway-flow: /origin/fetch` | Your application returned the rate limit. Honor its `Retry-After` header, if present, and inspect application-level limits. | +| `500` | `x-gateway-flow` ending in `/error` | The gateway encountered an internal error. Retry only safe requests, and contact support if it persists. | +| `502` | `x-gateway-flow: /origin/fetch/error` | The gateway could not get a usable response from the origin after a connection or platform error. Contact support if it persists. | +| `503` | `x-gateway-flow: /origin/fetch/error` and `Retry-After` | Origin compute was temporarily throttled. Honor `Retry-After` before retrying a safe request. | +| `504` | `x-gateway-flow: /origin/fetch/error` | Origin work exceeded the [request duration limit](quotas.md#requests-responses). Reduce the work performed during the request. | +| `5xx` | No `x-gateway-flow` | The failure may have occurred before the request reached the gateway. Preserve the Ray IDs and `Retry-After`, if present, when contacting support. | Log these fields individually from trusted server-side code. Do not log query strings unless you have removed sensitive values. Never dump complete request From 468c3a52fca0497685ef5a948b4e2efaaf9be870 Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Mon, 17 Aug 2026 17:06:42 -0400 Subject: [PATCH 7/8] Tabulate diagnostic response headers --- docs/cloud/diagnostics.md | 40 ++++++++++++--------------------------- 1 file changed, 12 insertions(+), 28 deletions(-) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index 7887b5d07..15a0bef10 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -6,29 +6,18 @@ description: Safely collect useful details when diagnosing failed requests to Cr ## Response Headers -The `x-gateway-flow` header identifies how Craft Cloud produced the response. -For example, `/origin/fetch` means the gateway fetched the environment’s -origin, while `/origin/reject` means it rejected the request before contacting -the origin. - -The `x-gateway-http-signature` header reports whether Craft Cloud detected and -validated [request signing](request-signing.md). A value of `verified` means -validation succeeded; `unverified` means signing was detected but validation -failed. - -The `cf-ray` header identifies the request in Cloudflare, while -`cf-cache-status` describes how Cloudflare handled it in the cache. See -[Troubleshooting Static Caching](static-caching.md#troubleshooting) for common -cache statuses. - -### Cloudflare O2O - -When [Cloudflare O2O](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/) -routes a request through both a customer zone and Craft Cloud’s SaaS provider -zone, `cf-ray` and `cf-cache-status` describe the customer zone. -`x-gateway-cf-ray` and `x-gateway-cf-cache-status` provide the corresponding -Ray ID and cache status for the Craft Cloud zone. Preserve both sets when they -are present so Craft support can correlate the request. +- `cf-*` headers come from Cloudflare. +- `x-gateway-*` headers are added by the Craft Cloud gateway. +- All other headers are returned by the origin (Craft). + +| Response Header | Description | +| --- | --- | +| x-gateway-flow | Identifies how Craft Cloud produced the response. `/origin/fetch` means the gateway fetched the environment’s origin, while `/origin/reject` means it rejected the request before contacting the origin. | +| x-gateway-http-signature | Reports whether Craft Cloud detected and validated [request signing](request-signing.md). `verified` means validation succeeded; `unverified` means signing was detected but validation failed. | +| cf-ray | Identifies the request in Cloudflare. For [Cloudflare O2O](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/), this is the customer zone Ray ID. | +| cf-cache-status | Describes how Cloudflare handled the response in the cache. For Cloudflare O2O, this is the customer zone cache status. See [Troubleshooting Static Caching](static-caching.md#troubleshooting) for common values. | +| x-gateway-cf-ray | For Cloudflare O2O, the Ray ID for Craft Cloud’s SaaS provider zone. | +| x-gateway-cf-cache-status | For Cloudflare O2O, the cache status for Craft Cloud’s SaaS provider zone. | ## Interpreting Failures @@ -50,8 +39,3 @@ it with `x-gateway-flow` and the other diagnostic headers: | `503` | `x-gateway-flow: /origin/fetch/error` and `Retry-After` | Origin compute was temporarily throttled. Honor `Retry-After` before retrying a safe request. | | `504` | `x-gateway-flow: /origin/fetch/error` | Origin work exceeded the [request duration limit](quotas.md#requests-responses). Reduce the work performed during the request. | | `5xx` | No `x-gateway-flow` | The failure may have occurred before the request reached the gateway. Preserve the Ray IDs and `Retry-After`, if present, when contacting support. | - -Log these fields individually from trusted server-side code. Do not log query -strings unless you have removed sensitive values. Never dump complete request -headers, environment variables, or credentials. In particular, never log the -Craft Cloud signing key, GraphQL tokens, or other secrets. From 73720dcb4d025e81c9b300b9657c8a8122fca4cb Mon Sep 17 00:00:00 2001 From: Tim Kelty Date: Tue, 18 Aug 2026 06:53:33 -0400 Subject: [PATCH 8/8] Tighten Craft Cloud diagnostics guidance --- docs/.vuepress/theme/styles/code.pcss | 4 +++ docs/cloud/diagnostics.md | 50 +++++++++++++-------------- 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/.vuepress/theme/styles/code.pcss b/docs/.vuepress/theme/styles/code.pcss index 673db3a25..68200ca46 100644 --- a/docs/.vuepress/theme/styles/code.pcss +++ b/docs/.vuepress/theme/styles/code.pcss @@ -91,6 +91,10 @@ } } +.cloud-diagnostics .theme-default-content code { + white-space: nowrap; +} + /** * Styling to emphasize placeholders within fenced code blocks. * (This is something we added to VuePress.) diff --git a/docs/cloud/diagnostics.md b/docs/cloud/diagnostics.md index 15a0bef10..5f5ff5083 100644 --- a/docs/cloud/diagnostics.md +++ b/docs/cloud/diagnostics.md @@ -1,41 +1,41 @@ --- -description: Safely collect useful details when diagnosing failed requests to Craft Cloud. +description: Diagnose failed requests to Craft Cloud. +pageClass: cloud-diagnostics --- # Diagnostics ## Response Headers -- `cf-*` headers come from Cloudflare. -- `x-gateway-*` headers are added by the Craft Cloud gateway. -- All other headers are returned by the origin (Craft). +- `cf-*`: Cloudflare +- `x-gateway-*`: Craft Cloud gateway +- All others: origin (Craft) | Response Header | Description | | --- | --- | -| x-gateway-flow | Identifies how Craft Cloud produced the response. `/origin/fetch` means the gateway fetched the environment’s origin, while `/origin/reject` means it rejected the request before contacting the origin. | -| x-gateway-http-signature | Reports whether Craft Cloud detected and validated [request signing](request-signing.md). `verified` means validation succeeded; `unverified` means signing was detected but validation failed. | -| cf-ray | Identifies the request in Cloudflare. For [Cloudflare O2O](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/), this is the customer zone Ray ID. | -| cf-cache-status | Describes how Cloudflare handled the response in the cache. For Cloudflare O2O, this is the customer zone cache status. See [Troubleshooting Static Caching](static-caching.md#troubleshooting) for common values. | -| x-gateway-cf-ray | For Cloudflare O2O, the Ray ID for Craft Cloud’s SaaS provider zone. | -| x-gateway-cf-cache-status | For Cloudflare O2O, the cache status for Craft Cloud’s SaaS provider zone. | +| `x-gateway-flow` | How Craft Cloud produced the response. For example, `/origin/fetch` reached Craft. | +| `x-gateway-http-signature` | [Request-signing](request-signing.md) result. `verified` succeeded; `unverified` was detected but failed validation. | +| `cf-ray` | Cloudflare request ID.1 | +| `cf-cache-status` | Cloudflare [cache status](static-caching.md#troubleshooting).1 | +| `x-gateway-cf-ray` | Cloudflare request ID.2 | +| `x-gateway-cf-cache-status` | Cloudflare [cache status](static-caching.md#troubleshooting).2 | + +1 With [Cloudflare O2O](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/) requests, the marked headers describe the customer zone. + +2 The marked headers describe the Craft Cloud zone and are only present with [Cloudflare O2O](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/) requests. ## Interpreting Failures -A status code describes the outcome, but not which layer produced it. Combine -it with `x-gateway-flow` and the other diagnostic headers: +Status alone does not identify the response layer. Use it with the diagnostic +headers: | Status | Response Headers | Interpretation | | --- | --- | --- | -| `4xx/5xx` | `x-gateway-flow: /origin/fetch` | Your application returned the response. Inspect its logs and error handling. | -| `400` | `x-gateway-flow: /origin/reject` | The request body failed gateway validation. Fix the request rather than retrying it unchanged. | -| `401` | `x-gateway-http-signature: unverified` | A signature-protected gateway endpoint rejected an invalid or expired signature. Check the signing key, method, target URL, timestamp, and expiry before signing again. | -| `403` | `x-gateway-flow: /origin/reject` | A gateway request policy blocked the request before it reached your application. Do not retry it unchanged. | -| `404` | `x-gateway-flow: /` | The gateway could not match the hostname to a Craft Cloud environment. Check the requested hostname. | -| `413` | `x-gateway-flow: /origin/reject` | The request body was too large for the origin request path. Reduce its size. | -| `429` | `x-gateway-flow: /origin/reject` and `Retry-After` | The gateway rate limited the request before it reached your application. Honor `Retry-After`. A `verified` signature confirms signing worked, but does not bypass shared capacity limits. | -| `429` | `x-gateway-flow: /origin/fetch` | Your application returned the rate limit. Honor its `Retry-After` header, if present, and inspect application-level limits. | -| `500` | `x-gateway-flow` ending in `/error` | The gateway encountered an internal error. Retry only safe requests, and contact support if it persists. | -| `502` | `x-gateway-flow: /origin/fetch/error` | The gateway could not get a usable response from the origin after a connection or platform error. Contact support if it persists. | -| `503` | `x-gateway-flow: /origin/fetch/error` and `Retry-After` | Origin compute was temporarily throttled. Honor `Retry-After` before retrying a safe request. | -| `504` | `x-gateway-flow: /origin/fetch/error` | Origin work exceeded the [request duration limit](quotas.md#requests-responses). Reduce the work performed during the request. | -| `5xx` | No `x-gateway-flow` | The failure may have occurred before the request reached the gateway. Preserve the Ray IDs and `Retry-After`, if present, when contacting support. | +| `4xx/5xx` | `x-gateway-flow: /origin/fetch` | Returned by Craft; check application logs. | +| `400/403/413` | `x-gateway-flow: /origin/reject` | Detected invalid or malicious request. | +| `401` | `x-gateway-http-signature: unverified` | The signature was invalid or expired. | +| `404` | `x-gateway-flow: /` | Hostname did not match a Craft Cloud environment. | +| `429/503` | `Retry-After: 𝑛` | Automate retry, honoring `Retry-After`. | +| `500/502` | No `x-gateway-flow: /origin/fetch` | A gateway error occurred; contact support if it persists. | +| `504` | `x-gateway-flow: /origin/fetch/error` | The origin exceeded the [request duration limit](quotas.md#requests-responses). | +| `5xx` | No `x-gateway-flow` | The error occurred before the gateway, either in the `craft.cloud` zone or a parent Cloudflare zone. |