504

Two codes, one client action. request_timeout is the API's own answer: the request passed its 50-second limit (error.details.timeout_seconds is 50), or a search inside it timed out. gateway_timeout means the proxy in front of the API stopped waiting first, at 58 seconds; it is a rare backstop. Neither means the request was malformed, and a request that times out returns no records, so it is never billed. Both carry Retry-After. Set your HTTP client's timeout to at least 55 seconds so you receive request_timeout instead of abandoning the request and seeing a bare network error such as ECONNABORTED; use 60 seconds to receive the proxy's gateway_timeout as well. A 504 with no JSON body came from the load balancer; treat it the same way. On MCP the timeout is the JSON-RPC error -32007 — see MCP errors.

Retry with exponential backoff, starting at Retry-After seconds. If the same request keeps timing out, it is too expensive as written: follow the cursor instead of a deep offset, lower limit, or narrow the filters or free-text term. Check that your client timeout is at least 55 seconds.