O que significa um erro 503 Service Unavailable e de quem é a culpa

Um 503 Service Unavailable é o único erro de servidor que normalmente é de propósito. Alguma coisa decidiu que este pedido não ia ser servido agora, e disse-o, em vez de tentar e falhar.

Isso faz dele o esquisito da família. Um 500 é código que partiu enquanto corria. Um 502 é um proxy a receber uma resposta inutilizável daquilo que tem atrás. Um 504 é essa mesma coisa a nunca responder a tempo. Os três são falhas. Um 503 é uma decisão.

As quatro coisas que tomam essa decisão

Num navegador parecem idênticas e significam coisas completamente diferentes para quem gere o site.

Modo de manutenção. Alguém pôs o site deliberadamente atrás de uma página de espera enquanto corre uma migração ou aterra um deploy. Aqui o 503 funciona exactamente como foi desenhado, e é o único caso em que a resposta certa é voltar mais tarde.

A aplicação não está a aceitar ligações. Todos os workers estão ocupados, a pool de ligações está cheia, a fila à frente dela está no limite. O servidor da frente ainda está de pé e ainda responde, por isso responde com a única coisa honesta que tem: agora não.

Um limitador de taxa. Você, ou a rede em que está, enviou mais pedidos do que um limiar permite. Alguns serviços usam um 429 para isto, que é mais específico e mais útil; muitos usam 503, e uma CDN à frente de uma aplicação transforma muitas vezes um no outro.

Não está nada a correr. Um autoscaler que não acompanhou um pico de tráfego, um deploy em que a versão nova não passou o health check, um contentor que morreu e não foi substituído. O balanceador de carga tem destinos saudáveis para onde mandar tráfego, não encontra nenhum, e devolve um 503 porque não há para onde o mandar.

Só o primeiro destes é planeado. Os outros três são o sistema a dizer que está no limite ou que perdeu alguma coisa, na forma delicada reservada a uma condição temporária.

O cabeçalho que quase ninguém lê

Um 503 é o código de estado que traz uma resposta agarrada. A resposta pode levar Retry-After, que diz ou quantos segundos esperar ou a data e hora exactas a que voltar:

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/html

Isso é o site a dizer-lhe que vão ser dois minutos. As páginas de manutenção bem configuradas põem-no, as CDN deixam-no passar, e enviá-lo não custa nada.

Daí seguem-se duas coisas, e apontam em direcções opostas. Se está a escrever um cliente, leia o cabeçalho em vez de inventar o seu próprio backoff: a um serviço que lhe disse 120 segundos e leva uma nova tentativa de dois em dois está a pedir-se que sirva precisamente os pedidos que acabou de dizer que não conseguia servir. E se gere o site, ponha-o. Um 503 com Retry-After é um motor de busca a segurar a página em vez de a tratar como desaparecida, e um cliente que espera como deve ser em vez de um que soma à carga que causou o problema.

Se é o visitante

Um 503 normalmente significa esperar e, coisa invulgar num erro, esperar muitas vezes resulta. Recarregue ao fim de um ou dois minutos. Se for um deploy ou um pico, resolve-se sozinho, e não há nada no seu navegador que lhe toque de qualquer maneira.

A única coisa que vale a pena verificar é se é só consigo. Um 503 que toda a gente apanha é a capacidade do site ou a sua janela de manutenção. Um 503 que você apanha e um colega noutra rede não apanha é mais provavelmente um limitador de taxa que ficou com implicância com o seu endereço, e um telemóvel com dados responde a essa pergunta em uns dez segundos. É a essa distinção que se resume todo o distinguir o seu bug da falha deles.

Se o site é seu

A resposta não lhe diz quase nada mas, ao contrário de um 500, a causa está normalmente à frente da aplicação e não dentro dela.

Comece por saber que camada o emitiu. Um 503 do nginx, de um balanceador de carga ou de uma CDN é igual para o navegador e vem de três sítios diferentes com três logs diferentes. Muitas vezes o corpo denuncia-o, porque cada um deles traz a sua própria página por omissão, e os cabeçalhos de resposta costumam nomear aquilo que os produziu. Se a sua aplicação nunca chegou a correr, o log dela vai estar em silêncio, e esse silêncio é uma prova e não um beco sem saída.

Depois a pergunta óbvia, fácil de saltar quando um site está em baixo: o modo de manutenção ainda está ligado? Uma página de espera que era para durar dez minutos e sobreviveu ao deploy que a levantou é um 503 suficientemente comum para se ver primeiro, e excluí-lo leva segundos.

Se for capacidade, a solução não está na página de erro. Olhe para a saturação dos workers, os limites da pool e a profundidade da fila ao longo da janela, em vez de olhar para os pedidos que apanharam o 503, porque os que apanharam o 503 são os que chegaram depois de o problema começar. Se forem os health checks, a pergunta é se o check tem razão em dizer que a aplicação não está saudável ou se está a falhar por um motivo próprio, e esses dois casos pedem respostas opostas.

Porque é que um 503 merece ser reportado como deve ser

A maioria dos 503 resolve-se. É precisamente isso que os torna escorregadios: quando alguém vai investigar, o site voltou e não há nada para ver. O que sobra é a memória que alguém tem de uma página de erro e uma suspeita sobre mais ou menos quando.

Problemas de capacidade e rollouts maus não se repetem a pedido. Acontecem no momento em que o tráfego atravessou uma linha, e a prova deles é uma janela num gráfico que ninguém sabe que tem de ir ver a não ser que alguém tenha apontado quando aconteceu.

Para um 503 a parte útil é a marca temporal e os cabeçalhos de resposta: que camada respondeu, que Retry-After declarou, e o minuto exacto. Isso chega para encontrar a janela certa num painel, que é onde a resposta vive de facto.

Num parágrafo

Um 503 Service Unavailable significa que alguma coisa escolheu não servir o pedido em vez de tentar e falhar, e é isso que o separa de um 500, de um 502 e de um 504. Quatro coisas fazem essa escolha: o modo de manutenção, uma aplicação que ficou sem capacidade, um limitador de taxa, e um balanceador de carga sem nada saudável para onde mandar tráfego. Só a primeira é planeada. Se está de visita, espere um minuto e depois veja se mais alguém o está a ver. Se o site é seu, descubra primeiro que camada respondeu, certifique-se de que o modo de manutenção não ficou simplesmente ligado, e ponha Retry-After para que os clientes que esperam esperem como deve ser em vez de somarem à carga.