Upstream failure field note
API 502 vs 503 vs 504: choose the right recovery path
Separate bad gateway responses, temporary service unavailability, and upstream timeouts before adding API retries.
These statuses all point beyond ordinary request validation, but not to the same failure. A 502 is an invalid upstream response, 503 is temporary unavailability or overload, and 504 is an upstream timeout. Preserve the request ID and timing because the provider may have partially executed the operation.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Classify the boundary
Record which gateway or provider emitted the response and whether a proxy, CDN, load balancer, or third-party dependency sits in front of the API.
- 02
Decide if replay is safe
Reads are usually safer than writes. Protect write retries with an idempotency key or a durable operation identifier.
- 03
Bound the retry
Honor Retry-After, use jitter, cap attempts, and surface a circuit-breaker state instead of creating a retry storm.
POST /orders → 504 Gateway Timeout → immediate blind retry
Check operation ID → wait with jitter → query order state before another write
Evidence
HTTP 429: A rate, quota, concurrency, or resource lock limit blocked the request.
Retry-After is present; it should take precedence over a guessed delay.
The reported request window has no remaining capacity.
Next checks
01Parse Retry-After as either delta-seconds or an HTTP date before scheduling the next attempt.
No account · no upload · no endpoint calledOpen the full incident decoder and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every gateway response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the MDN — 504 Gateway Timeout. Recheck your pinned provider/API version before production deployment.