5xx and Timeouts: The Problem Is on Theirs

Sunday, 03:07. Vera has scheduled an early run of the Thursday report's data pull, and it comes back with 503 Service Unavailable. For once there is nothing to fix, because there is nothing wrong: Tandem's maintenance window runs from 03:00 to 03:20 every Sunday, the documentation says so, and the response says so too. The request was perfect. The other side was simply closed.

The 5xx family and its cousin the timeout are the weather of APIs. They are not your fault, they are partly forecastable, and they are survivable if you behave well while they last. The whole skill on this page is learning to recognize weather rather than mistaking it for something you did — and then waiting in a way that helps.

The 5xx Regulars

Four numbers cover nearly everything you will meet. A 500 means the server hit its own bug while handling a perfectly good request — something broke inside, and the message is often deliberately vague because the details are the provider's business, not a caller's.

A 502 and a 504 both point at a middleman. Requests rarely travel straight from your machine to the program that answers them; there is usually something in between that receives the request and passes it along. When that go-between cannot get a usable answer out of the program behind it — no answer at all, or a broken one — you get 502; when it is still waiting and finally gives up, you get 504. You do not have to know what the middleman is called to read the signal: something in their chain did not respond.

A 503 means the service is deliberately not answering right now — overloaded, or in maintenance. This is the friendliest of the four, because it often arrives with a header called Retry-After, which is the server scheduling your patience for you. Vera's Sunday response carries one.

HTTP/1.1 503 Service Unavailable
Retry-After: 780
Content-Type: application/json

{"error": {"code": "maintenance",
           "message": "Scheduled maintenance, back at 03:20",
           "request_id": "req_9f2c"}}

Read it the way Topic 29 taught. The status says the problem is on their side. The message names the reason and the reopening time. And the header holds a number of seconds — seven hundred and eighty of them, which is the thirteen minutes still left in the window at 03:07. (Some APIs write the same header as a date and time instead; both forms are legal and mean the same thing — come back then.) There is nothing here to debug. There is a time to come back.

Timeouts: the Non-Answer

Sometimes nothing comes back at all. You send the request, the terminal sits there, and after a while curl gives up and tells you it timed out. That is not a status code, because a status code requires a response, and this is the case where no response arrived.

Here is the honest and slightly uncomfortable part. A timeout tells you nothing about whether your request was carried out. It may have never arrived. It may have arrived and been ignored. Or it may have arrived, been fully carried out, and had its answer die on the way back to you. From where you sit, those three look identical.

For a request that only reads data, the ambiguity costs nothing — ask again and look. For a request that creates something, it matters a great deal, and it is the reason the next page exists.

What Your Side Does

Read the body anyway. A 503 frequently explains itself, and a 500 sometimes carries a request id worth keeping. Then honor whatever the response asked of you: if Retry-After is there, that number is not a suggestion, it is the provider telling you when trying again will actually work.

If there is no such header, wait with intention rather than reflex. Try once after a short pause, and if that fails wait longer before the next attempt, and longer again after that. The word for this pattern is backoff — each retry spaced further apart than the last — and the next chapter puts it to work properly against rate limits.

And before deciding the world has ended, check the provider's status page: a page the provider maintains to say publicly whether their service is healthy. Tandem has one, and on that Sunday morning it says exactly what the response said. Two minutes there beats an hour of suspicion.

Evidence, Not Vigils

What you never do is hammer. Sixty identical requests a minute against a struggling server add load to the exact thing that is struggling, and they spend your own quota telling you the same bad news over and over. Persistence is a virtue in many places; against an overloaded service it is a contribution to the overload.

Instead, take notes while you wait. The time, the status, the request id from the body, the endpoint you called. If the trouble outlasts the posted window — if it is 03:35 and the 503 is still there — that little bundle is your escalation, and the last page of this chapter turns it into an email that gets answered on the first reply. Vera reruns her pull at 03:21 and the report never learns anything happened.