Guia de erros

Erros 5xx de servidor

A classe que significa que o servidor não conseguiu atender uma requisição que, até onde ele podia dizer, era válida.

Um status 5xx significa que o servidor não conseguiu atender uma requisição que parecia válida. A responsabilidade está do lado do servidor: a aplicação, suas dependências ou a infraestrutura na frente dela. Ao contrário de um 4xx, nenhuma mudança que o cliente pudesse fazer o teria evitado.

Esta é a classe para a qual o monitoramento existe, e todo código dela deve fazer uma verificação falhar por padrão. É também a classe mais visível para os clientes, porque um 5xx geralmente significa que uma requisição que deveria ter funcionado não funcionou.

O código específico mostra qual camada falhou, e isso é a maior parte da triagem inicial: 500 é a aplicação lançando uma exceção; 502 e 504 são um proxy informando que algo atrás dele falhou ou foi lento demais; 503 é uma recusa deliberada por capacidade ou manutenção; 501 é um método que o servidor não implementa. Chegar rápido à camada certa vale mais do que qualquer quantidade de palpites sobre as causas.

Lista de códigos de erro 5xx: os erros de servidor registrados, mais o 509 e os códigos 52x da Cloudflare
CódigoNomeDefinido em
500Internal Server ErrorRFC 9110
501Not ImplementedRFC 9110
502Bad GatewayRFC 9110
503Service UnavailableRFC 9110
504Gateway TimeoutRFC 9110
505HTTP Version Not SupportedRFC 9110
506Variant Also NegotiatesRFC 2295
507Insufficient StorageRFC 4918 (WebDAV)
508Loop DetectedRFC 5842 (WebDAV)
509Bandwidth Limit ExceededNão registrado: enviado por alguns provedores de hospedagem quando uma conta esgota sua cota de banda
510Not ExtendedRFC 2774, hoje obsoleta
511Network Authentication RequiredRFC 6585
520Web Server Returns an Unknown ErrorCloudflare, não registrado
521Web Server Is DownCloudflare, não registrado
522Connection Timed OutCloudflare, não registrado
523Origin Is UnreachableCloudflare, não registrado
524A Timeout OccurredCloudflare, não registrado
525SSL Handshake FailedCloudflare, não registrado
526Invalid SSL CertificateCloudflare, não registrado

Causas comuns

  • Uma exceção não tratada no código da aplicação.
  • Uma dependência (banco de dados, cache, fila, API de terceiros) falhando ou estourando o tempo.
  • Esgotamento de recursos: memória, descritores de arquivo, pools de conexão, disco.
  • Um deploy que entregou um bug, ou uma mudança de configuração que quebrou uma conexão.
  • Um serviço upstream fora do ar, inacessível ou respondendo devagar demais.

Como diagnosticar

  1. Leia primeiro o código exato: ele identifica a camada, e a camada determina onde procurar.
  2. Veja se o erro está no log da sua aplicação ou só no do proxy: só isso já divide a busca pela metade.
  3. Descubra se ele afeta todas as requisições ou só uma parte, o que distingue uma falha total de uma parcial.
  4. Cruze o horário de início com deploys, mudanças de configuração e incidentes de dependências.
  5. Verifique a saúde de cada dependência antes de depurar o seu próprio código; a maioria dos incidentes 5xx é a queda de outra pessoa chegando até você.

De quem é a culpa? Do lado do servidor

Por definição, do lado do servidor, embora um 5xx muitas vezes seja causado por uma dependência e não pela própria aplicação, e continua sendo o seu incidente mesmo quando o bug não é seu.

O que o monitoramento vê

Os critérios padrão da Uptimely fazem uma verificação falhar diante de um 5xx e registram o código exato. Um monitor declara um incidente quando o limite de falhas é atingido (duas verificações com falha seguidas, por padrão), então uma falha isolada é registrada como indisponibilidade sem acionar ninguém, enquanto um 5xx persistente abre um incidente e executa a política de plantão.

Perguntas

Todo 5xx deve disparar um alerta?

Todo 5xx deve fazer a verificação falhar. Se ele alerta depende do limite: esperar duas falhas seguidas elimina as falhas isoladas sem deixar de registrá-las como indisponibilidade, o que quase sempre é o padrão certo.

Quais códigos 5xx apontam para um proxy e não para a minha aplicação?

502 e 504 são gerados por algo na frente da sua aplicação: um proxy reverso ou uma CDN informando que o upstream falhou ou foi lento demais. Um 500 vem da própria aplicação.

Um dos guias de erros HTTP e de rede da Uptimely, escritos para quem opera o servidor, e não para quem recarrega a página. Something here read wrong to you? Email support@getuptimely.com.

Verificado em pela equipe do Uptimely.