Gerar respostas de erro personalizadas - Amazon CloudFront

Gerar respostas de erro personalizadas

Se um objeto fornecido pelo CloudFront estiver indisponível por algum motivo, seu servidor web normalmente retornará um código de status HTTP relevante para o CloudFront para indicar isso. Por exemplo, se um visualizador solicitar uma URL inválida, seu servidor web retornará um código de status HTTP 404 (Não encontrado) para o CloudFront e o CloudFront retorna esse código de status para o visualizador.

Você pode configurar o CloudFront para retornar uma resposta de erro personalizada ao visualizador, se desejar. Você também tem várias opções para gerenciar como o CloudFront responde quando há um erro. Para especificar opções para mensagens de erro personalizadas, atualize a distribuição do CloudFront para especificar esses valores. Para obter mais informações, consulte Configurar o comportamento de resposta a erros.

Se você configurar o CloudFront para retornar uma página de erro personalizada para um código de status HTTP, mas a página de erro personalizada não estiver disponível, o CloudFront retornará ao visualizador o código de status recebido do CloudFront da origem que contém as páginas de erro personalizadas. Por exemplo, suponha que sua origem personalizada retorne um código de status 500 e você configurou o CloudFront para obter uma página de erro personalizada para esse código em um bucket do Amazon S3. Porém, alguém excluiu a página de erro personalizada do bucket por acidente. O CloudFront retorna um código de status HTTP 404 (Não encontrado) para o visualizador que solicitou o objeto.

Quando o CloudFront retorna uma página de erro personalizada ao visualizador, você paga as cobranças padrão equivalentes do CloudFront para a página de erro personalizada, e não as cobranças do objeto solicitado. Para obter mais informações sobre as cobranças do CloudFront, consulte Definição de preço do Amazon CloudFront.

Configurar o comportamento de resposta a erros

Para configurar respostas de erro personalizadas, você pode usar o console e a API do CloudFront ou o AWS CloudFormation. Independentemente de como você optar por atualizar a configuração, considere as seguintes dicas e recomendações:

  • Salve suas páginas de erro personalizadas em um local acessível ao CloudFront. Recomendamos que você os armazene em um bucket do Amazon S3 e que você não os armazene no mesmo local que o restante do conteúdo do seu site ou aplicativo. Se você armazenar as páginas de erro personalizadas na mesma origem do seu site ou aplicativo e a origem começar a retornar erros 5xx, o CloudFront não poderá obter as páginas de erro personalizadas porque o servidor de origem não está disponível. Para obter mais informações, consulte Armazenar objetos e páginas de erro personalizadas em diferentes locais.

  • Certifique-se de que o CloudFront tenha permissão para obter suas páginas de erro personalizadas. Se as páginas de erro personalizadas forem armazenadas no Amazon S3, elas deverão estar acessíveis ao público ou você deve configurar um controle de acesso à origem (OAC) do CloudFront. Se as páginas de erro personalizadas forem armazenadas em uma origem personalizada, as páginas deverão estar acessíveis publicamente.

  • (Opcional) Configure sua origem para adicionar um Cache-Control ou Expires cabeçalho junto com as páginas de erro personalizadas, se desejar. Você também pode usar a configuração de TTL mínimo de cache de erro para controlar por quanto tempo o CloudFront armazena em cache as páginas de erro personalizadas. Para obter mais informações, consulte Controlar por quanto tempo o CloudFront detecta erros.

Configure respostas de erro personalizadas (console do CloudFront)

Para configurar respostas de erro personalizadas no console do CloudFront, você deve ter uma distribuição do CloudFront. No console, as configurações para respostas de erro personalizadas só estão disponíveis para distribuições existentes. Para saber como criar uma distribuição, consulte Conceitos básicos de uma distribuição simples do CloudFront.

Para configurar respostas de erro personalizadas (console)

  1. Faça login no AWS Management Console e abra a página Distributions (Distribuições) no console do CloudFront em https://console.aws.amazon.com/cloudfront/v3/home#distributions.

  2. Na lista de distribuições, escolha a distribuição a ser atualizada.

  3. Escolha a guia Error Pages (Páginas de erro) e escolha Create Custom Error Response (Criar resposta de erro personalizada).

  4. Insira os valores aplicáveis. Para obter mais informações, consulte Páginas de erro personalizadas e erro de armazenamento em cache em Values That You Specify When You Create or Update a Distribution (Valores que você especifica ao criar ou atualizar uma distribuição).

  5. Depois de inserir os valores desejados, escolha Create (Criar).

Configure respostas de erro personalizadas (API do CloudFront ou AWS CloudFormation)

Para configurar respostas de erro personalizadas com a API do CloudFront ou do AWS CloudFormation, use o tipo CustomErrorResponse em uma distribuição. Para obter mais informações, consulte:

Criar uma página de erro personalizada para códigos de status HTTP específicos

Se você preferir exibir uma mensagem de erro personalizada em vez da mensagem padrão, como por exemplo, uma página que usa a mesma formatação do resto do seu site, você pode fazer com que o CloudFront retorne ao visualizador um objeto (como um arquivo HTML) que contenha sua mensagem de erro personalizada.

Para especificar o arquivo que deseja retornar e os erros para os quais o arquivo deve ser retornado, atualize sua distribuição do CloudFront para especificar esses valores. Para obter mais informações, consulte Configurar o comportamento de resposta a erros.

Por exemplo, o seguinte item é uma página de erro personalizada:


				AWSPágina 404 da

Você pode especificar um objeto diferente para cada código de status HTTP compatível ou usar o mesmo objeto para todos os códigos de status compatíveis. Você pode optar por especificar páginas de erro personalizadas para alguns códigos de status e não para outros.

Os objetos fornecidos pelo CloudFront podem estar indisponíveis por vários motivos. Eles se encaixam em duas categorias gerais:

  • Erros de cliente indicam um problema com a solicitação. Por exemplo, um objeto com o nome especificado não está disponível ou o usuário não tem as permissões necessárias para obter um objeto no bucket do Amazon S3. Quando ocorre um erro de cliente, a origem retorna um código de status HTTP no intervalo 4xx para o CloudFront.

  • Erros do servidor indicam um problema com o servidor de origem. Por exemplo, o servidor HTTP está ocupado ou indisponível. Quando ocorre um erro de servidor, seu servidor de origem retorna um código de status HTTP no intervalo 5xx para o CloudFront ou o CloudFront não recebe uma resposta do seu servidor de origem por um determinado período de tempo e assume um código de status 504 (Tempo limite do Gateway).

Os códigos de status HTTP para os quais o CloudFront pode retornar uma página de erro personalizada incluem:

  • 400, 403, 404, 405, 414, 416

    nota

    É possível criar uma página de erro personalizada para o código de status HTTP 416 (intervalo solicitado insatisfatório) e alterar o código de status HTTP retornado pelo CloudFront aos visualizadores quando a origem retornar um código de status 416 ao CloudFront. (Para obter mais informações, consulte Alterar códigos de resposta retornados pelo CloudFront.) No entanto, o CloudFront não armazena em cache as respostas do código de status 416, portanto, mesmo se você especificar um valor para o TTL mínimo de cache de erro para o código de status 416, o CloudFront não o usará.

  • 500, 501, 502, 503, 504

    nota

    Em alguns casos, o CloudFront não retorna uma página de erro personalizada para o código de status HTTP 503, mesmo se você configurar o CloudFront para isso. Se o código de erro do CloudFront for Capacity Exceeded ou Limit Exceeded, o CloudFront retornará um código de status 503 ao visualizador sem usar sua página de erro personalizada.

Para obter uma explicação detalhada de como o CloudFront lida com respostas de erro de sua origem, consulte Como o CloudFront processa e armazena em cache códigos de status HTTP 4xx e 5xx da origem.

Armazenar objetos e páginas de erro personalizadas em diferentes locais

Se você quiser armazenar seus objetos e páginas de erro personalizadas em locais diferentes, sua distribuição deverá incluir um comportamento de cache para o qual o seguinte é verdadeiro:

  • O valor de Path Pattern é correspondente às suas mensagens de erro personalizadas. Por exemplo, imagine que você salvou páginas de erro personalizadas para erros 4xx em um bucket do Amazon S3 em um diretório denominado /4xx-errors. Sua distribuição deverá incluir um comportamento de cache para o qual o padrão de caminho roteia solicitações de suas páginas de erro personalizadas para esse local, por exemplo, /4xx-errors/*.

  • O valor de Origin especifica o valor de Origin ID da origem que contém suas páginas de erro personalizadas.

Para obter mais informações, consulte Configurações de comportamento de cache no tópico Valores especificados ao criar ou atualizar uma distribuição.

Alterar códigos de resposta retornados pelo CloudFront

Você pode configurar o CloudFront para retornar um código de status HTTP diferente para o visualizador do que o CloudFront recebeu da origem Por exemplo, se a origem retornar um código de status 500 para o CloudFront, você poderá solicitar que o CloudFront retorne uma página de erro personalizada e um código de status 200 (OK) ao visualizador. Há vários motivos pelos quais você pode querer que o CloudFront retorne um código de status ao visualizador diferente daquele retornado por sua origem ao CloudFront:

  • Alguns dispositivos de internet (alguns firewalls e proxies corporativos, por exemplo) interceptam códigos de status HTTP 4xx e 5xx e impedem que a resposta seja retornada ao visualizador. Neste caso, se você substituir 200, a resposta não será interceptada.

  • Se não for necessário distinguir diferentes erros de cliente ou erros de servidor, você pode especificar 400 ou 500 como o valor que o CloudFront retorna para todos os códigos de status 4xx ou 5xx.

  • Você pode retornar um código de status 200 (OK) e um site estático para que seus clientes não saibam que seu site está inativo.

Se você habilitar os logs padrão do CloudFront e configurar o CloudFront para alterar o código de status HTTP na resposta, o valor da coluna sc-status nos logs conterá o código de status especificado. No entanto, o valor da coluna x-edge-result-type não é afetado. Ele contém o tipo de resultado da resposta da origem. Por exemplo, digamos que você configure o CloudFront para retornar um código de status 200 ao visualizador quando a origem retornar 404 (Not Found) ao CloudFront. Quando a origem responde a uma solicitação com um código de status 404, o valor na coluna sc-status no log será 200, mas o valor na coluna x-edge-result-type será Error.

Você pode configurar o CloudFront para retornar qualquer um dos seguintes códigos de status HTTP junto com uma página de erro personalizada:

  • 200

  • 400, 403, 404, 405, 414, 416

  • 500, 501, 502, 503, 504

Controlar por quanto tempo o CloudFront detecta erros

Por padrão, quando a origem retorna um código de status HTTP 4xx ou 5xx, o CloudFront armazena essas respostas de erro em cache por 10 segundos. Por sua vez, o CloudFront envia a próxima solicitação do objeto à origem para ver se o problema que causou o erro foi resolvido e o objeto solicitado está disponível agora.

nota

É possível criar uma página de erro personalizada para o código de status HTTP 416 (intervalo solicitado insatisfatório) e alterar o código de status HTTP retornado pelo CloudFront aos visualizadores quando a origem retornar um código de status 416 ao CloudFront. (Para obter mais informações, consulte Alterar códigos de resposta retornados pelo CloudFront.) No entanto, o CloudFront não armazena em cache as respostas do código de status 416, portanto, mesmo se você especificar um valor para o TTL mínimo de cache de erro para o código de status 416, o CloudFront não o usará.

É possível especificar a duração, o Error Caching Minimum TTL (TTL mínimo de armazenamento em cache do erro), de cada código de status 4xx e 5xx armazenado em cache pelo CloudFront. Quando você especificar uma duração, observe o seguinte:

  • Se você especificar uma duração curta de armazenamento de erros em cache, o CloudFront encaminhará mais solicitações para a origem do que se você especificar um período maior. Para erros 5xx, isso pode agravar o problema que originalmente fez com que a origem retornasse um erro.

  • Quando a origem retorna um erro para um objeto, o CloudFront responde às solicitações do objeto com a resposta de erro ou com a página de erro personalizada até que a duração do armazenamento em cache expire. Se você especificar uma duração longa para o armazenamento de erros em cache, o CloudFront poderá continuar a responder às solicitações com uma resposta de erro ou com a página de erro personalizada por um longo período após o objeto se tornar disponível novamente.

Para controlar o tempo que o CloudFront armazena erros em cache para objetos individuais, configure seu servidor de origem para adicionar o cabeçalho aplicável à resposta de erro desse objeto:

  • Se a origem adicionar uma diretiva Cache-Control: max-age ou Cache-Control: s-maxage, ou um cabeçalho Expires:

    O CloudFront armazena em cache as respostas de erro para o maior valor no cabeçalho ou o valor de TTL mínimo de cache de erro.

    Lembre-se de que os valores Cache-Control: max-age e s Cache-Control: s-maxage não podem ser maiores que o valor de TLL máximo definido para o comportamento de cache para o qual a página de erro está sendo buscada.

  • Se a origem adicionar outras Cache-Control diretivas ou não adicionar cabeçalhos:

    O CloudFront armazena em cache as respostas de TTL mínimo de cache de erro.

Se o tempo de expiração de um código de status 4xx ou 5xx para um objeto for maior do que você deseja e o objeto estiver disponível novamente, você poderá invalidar o código de erro armazenado em cache usando a URL do objeto solicitado. Se a origem estiver retornando uma resposta de erro para vários objetos, você precisará invalidar cada objeto separadamente. Para obter mais informações sobre como invalidar objetos, consulte Invalidar arquivos.