[8.x] [Synthetics] Only return 404 if screenshot_ref is truly not present (#215241) (#218136)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[Synthetics] Only return 404 if `screenshot_ref` is truly not present
(#215241)](https://github.com/elastic/kibana/pull/215241)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Justin
Kambic","email":"jk@elastic.co"},"sourceCommit":{"committedDate":"2025-03-24T14:50:18Z","message":"[Synthetics]
Only return 404 if `screenshot_ref` is truly not present (#215241)\n\n##
Summary\n\nRight now we return a 404 anytime that the data we're looking
for on the\n`screenshot_ref` route is not satisfactory. We do an io-ts
check on the\ndata before returning. It's possible that that data will
fail the check,\nand we'd return a 404 anyway. This isn't a very
accurate reflection of\nwhat's happening on the server, and could
indicate a problem with the\nuser's data.\n\nInstead, we first check if
the data returned from Elasticsearch is\n`null`, and if it is we return
a 404. Otherwise, we compute the type\ncheck like normal and return the
result. In the case where the data\nfails the type check, we instead
return a 500 and include the malformed\ndata in the server
response.\n\nCo-authored-by: Faisal Kanout
<faisal.kanout@elastic.co>","sha":"74f87d99bc1981a533982e103f802d0cbf118fa7","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:enhancement","v9.0.0","backport:prev-minor","Team:obs-ux-management","v9.1.0"],"title":"[Synthetics]
Only return 404 if `screenshot_ref` is truly not
present","number":215241,"url":"https://github.com/elastic/kibana/pull/215241","mergeCommit":{"message":"[Synthetics]
Only return 404 if `screenshot_ref` is truly not present (#215241)\n\n##
Summary\n\nRight now we return a 404 anytime that the data we're looking
for on the\n`screenshot_ref` route is not satisfactory. We do an io-ts
check on the\ndata before returning. It's possible that that data will
fail the check,\nand we'd return a 404 anyway. This isn't a very
accurate reflection of\nwhat's happening on the server, and could
indicate a problem with the\nuser's data.\n\nInstead, we first check if
the data returned from Elasticsearch is\n`null`, and if it is we return
a 404. Otherwise, we compute the type\ncheck like normal and return the
result. In the case where the data\nfails the type check, we instead
return a 500 and include the malformed\ndata in the server
response.\n\nCo-authored-by: Faisal Kanout
<faisal.kanout@elastic.co>","sha":"74f87d99bc1981a533982e103f802d0cbf118fa7"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"9.0","label":"v9.0.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/215726","number":215726,"state":"MERGED","mergeCommit":{"sha":"349e4472ee62edd72cd062bb2635cb563f61168b","message":"[9.0]
[Synthetics] Only return 404 if `screenshot_ref` is truly not present
(#215241) (#215726)\n\n# Backport\n\nThis will backport the following
commits from `main` to `9.0`:\n- [[Synthetics] Only return 404 if
`screenshot_ref` is truly not
present\n(#215241)](https://github.com/elastic/kibana/pull/215241)\n\n\n\n###
Questions ?\nPlease refer to the [Backport
tool\ndocumentation](https://github.com/sorenlouv/backport)\n\n\n\nCo-authored-by:
Justin Kambic
<jk@elastic.co>"}},{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/215241","number":215241,"mergeCommit":{"message":"[Synthetics]
Only return 404 if `screenshot_ref` is truly not present (#215241)\n\n##
Summary\n\nRight now we return a 404 anytime that the data we're looking
for on the\n`screenshot_ref` route is not satisfactory. We do an io-ts
check on the\ndata before returning. It's possible that that data will
fail the check,\nand we'd return a 404 anyway. This isn't a very
accurate reflection of\nwhat's happening on the server, and could
indicate a problem with the\nuser's data.\n\nInstead, we first check if
the data returned from Elasticsearch is\n`null`, and if it is we return
a 404. Otherwise, we compute the type\ncheck like normal and return the
result. In the case where the data\nfails the type check, we instead
return a 500 and include the malformed\ndata in the server
response.\n\nCo-authored-by: Faisal Kanout
<faisal.kanout@elastic.co>","sha":"74f87d99bc1981a533982e103f802d0cbf118fa7"}}]}]
BACKPORT-->

x-pack/solutions/observability/plugins/synthetics/server/queries/journey_screenshots.ts

@@ -34,6 +34,10 @@ export const journeyScreenshotHandler = async ({
     stepIndex,
   });
 
+  if (result === null) {
+    return response.notFound();
+  }
+
   if (isRefResult(result)) {
     return response.ok({
       body: {
@@ -43,5 +47,11 @@ export const journeyScreenshotHandler = async ({
     });
   }
 
-  return response.notFound();
+  return response.custom({
+    statusCode: 500,
+    body: {
+      message: 'Screenshot metadata is not in the expected format',
+      screenshotRef: result,
+    },
+  });
 };