SDK Timeout Errors Developers Can Act On

Include the timeout you used, in seconds, and the host you called. A message that says 'timeout' could be DNS, TLS, or a slow handler. Those are different fixes.

Use a stable code such as REQUEST_TIMEOUT. HTTP 408 and a client-side deadline are not the same event. Do not collapse them into 'network error'.

If the SDK already retried twice, say so. Developers otherwise add their own loop and triple the load. If you did not retry, say the call failed once and what a safe retry looks like.

Honor a server Retry-After when you have one. Inventing a backoff on a 4xx validation error is how a sample hammers you.

A connect timeout means you never got a socket. A read timeout means the server accepted the call and then went quiet. The docs, the status page, and the firewall checklist are different.

Store that distinction on the probe with the route template. Do not store the full URL if it contains a token.

If new SDK versions time out on one route, the default deadline is too short or that route got slower. The inbox should show the version and the route, not a pile of unique stack traces that all mean the same wait.

Change the default or the doc in the same week. A draft issue that only says 'timeout' will sit forever.