fix(sentry-okhttp): Skip synthetic 504 for FORCE_CACHE cache misses

OkHttp's CacheInterceptor synthesizes a 504 "Unsatisfiable Request"
response when a request with `only-if-cached` (e.g. CacheControl.FORCE_CACHE)
misses the cache. This is not a real server error, so don't capture it
as a failed request event.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: markushi

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Fixes
+
+- Stop reporting OkHttp's synthetic 504 "Unsatisfiable Request" responses as errors for `CacheControl.FORCE_CACHE` (or any `only-if-cached`) cache misses ([#5276](https://github.com/getsentry/sentry-java/issues/5276))
+
 ## 8.39.1
 
 ### Fixes

sentry-okhttp/src/main/java/io/sentry/okhttp/SentryOkHttpInterceptor.kt

@@ -58,6 +58,8 @@ public open class SentryOkHttpInterceptor(
   private val failedRequestTargets: List<String> = listOf(DEFAULT_PROPAGATION_TARGETS),
 ) : Interceptor {
   private companion object {
+    private const val HTTP_GATEWAY_TIMEOUT = 504
+
     init {
       SentryIntegrationPackageStorage.getInstance()
         .addPackage("maven:io.sentry:sentry-okhttp", BuildConfig.VERSION_NAME)
@@ -386,6 +388,13 @@ public open class SentryOkHttpInterceptor(
       return false
     }
 
+    // A 504 on an only-if-cached (e.g. CacheControl.FORCE_CACHE) request is a synthetic
+    // cache-miss response generated by OkHttp's CacheInterceptor, not a real server error,
+    // so don't report it. See https://square.github.io/okhttp/recipes/#response-caching-kt-java
+    if (response.code == HTTP_GATEWAY_TIMEOUT && request.cacheControl.onlyIfCached) {
+      return false
+    }
+
     return true
   }
 

sentry-okhttp/src/test/java/io/sentry/okhttp/SentryOkHttpInterceptorTest.kt

@@ -31,6 +31,7 @@ import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 import kotlin.test.assertTrue
 import kotlin.test.fail
+import okhttp3.CacheControl
 import okhttp3.EventListener
 import okhttp3.Interceptor
 import okhttp3.MediaType.Companion.toMediaType
@@ -541,6 +542,30 @@ class SentryOkHttpInterceptorTest {
       )
   }
 
+  @Test
+  fun `does not capture a synthetic 504 from OkHttp for a FORCE_CACHE cache miss`() {
+    // No cache is configured on the client, so FORCE_CACHE is guaranteed to miss and
+    // OkHttp's CacheInterceptor will synthesize a 504 "Unsatisfiable Request" response.
+    val sut = fixture.getSut(captureFailedRequests = true)
+    val request =
+      Request.Builder()
+        .url(fixture.server.url("/hello"))
+        .cacheControl(CacheControl.FORCE_CACHE)
+        .build()
+    val response = sut.newCall(request).execute()
+
+    assertEquals(504, response.code)
+    verify(fixture.scopes, never()).captureEvent(any(), any<Hint>())
+  }
+
+  @Test
+  fun `captures a real 504 when onlyIfCached is not set`() {
+    val sut = fixture.getSut(captureFailedRequests = true, httpStatusCode = 504)
+    sut.newCall(getRequest()).execute()
+
+    verify(fixture.scopes).captureEvent(any(), any<Hint>())
+  }
+
   @SuppressWarnings("SwallowedException")
   @Test
   fun `does not capture an error even if it throws`() {