Add Craft Cloud diagnostics guidance #782
+46
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| --- | ||
| description: Diagnose failed requests to Craft Cloud. | ||
| pageClass: cloud-diagnostics | ||
| --- | ||
|
|
||
| # Diagnostics | ||
|
|
||
| ## Response Headers | ||
|
|
||
| - `cf-*`: Cloudflare | ||
| - `x-gateway-*`: Craft Cloud gateway | ||
| - All others: origin (Craft) | ||
|
|
||
| | Response Header | Description | | ||
| | --- | --- | | ||
| | `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.<sup>1</sup> | | ||
| | `cf-cache-status` | Cloudflare [cache status](static-caching.md#troubleshooting).<sup>1</sup> | | ||
| | `x-gateway-cf-ray` | Cloudflare request ID.<sup>2</sup> | | ||
| | `x-gateway-cf-cache-status` | Cloudflare [cache status](static-caching.md#troubleshooting).<sup>2</sup> | | ||
|
|
||
| <sup>1</sup> 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. | ||
|
|
||
| <sup>2</sup> 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 | ||
|
|
||
| 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` | 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`. | | ||
|
There was a problem hiding this comment.
For non-idempotent requests such as GraphQL mutations or form submissions, automatically retrying every Useful? React with 👍 / 👎. |
||
| | `500/502` | No `x-gateway-flow: /origin/fetch` | A gateway error occurred; contact support if it persists. | | ||
|
There was a problem hiding this comment.
When a Useful? React with 👍 / 👎. |
||
| | `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. | | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This exhaustive attribution is incorrect for intermediary-generated standard headers. In particular, Craft Cloud's gateway and capacity-limiting paths can emit the unprefixed
Retry-Afterused later on this page, and Cloudflare or the gateway may also add or rewrite fields such asDate,Server, andContent-Length; readers could therefore misidentify the response layer. Restrict this statement to known origin headers instead of treating every non-cf-*/x-gateway-*header as origin data.Useful? React with 👍 / 👎.