# Configurações de custom page Um conjunto de custom pages substitui as respostas de erro de um [workload](/pt-br/documentacao/plataforma/workloads/) por páginas suas. Ele contém uma página por código de status HTTP, e cada página busca seu conteúdo em um [connector](/pt-br/documentacao/plataforma/connectors/), o mantém em cache pelo próprio tempo e pode responder com outro código de status. Um workload usa um conjunto apenas quando você atribui o conjunto no deployment do workload, em `strategy.attributes.custom_page`. Para os campos do deployment, consulte [Configurações de workload](/pt-br/documentacao/plataforma/workloads/configuracoes/#deployment). --- ## Interfaces Três interfaces escrevem um conjunto de custom pages, e o deployment de um workload o atribui. As tabelas desta página nomeiam o controle do Console e o campo da API de cada configuração. | Interface | Criar | Ler, atualizar, excluir | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [Azion Console](https://console.azion.com/) | O menu **Custom Pages** em `/custom-pages` e, em seguida, a página **Create Custom Page** | A página **Edit Custom Page** | | [Azion API v4](https://api.azion.com/v4#/operations/GetWorkspaceCustomPages) | `POST /v4/workspace/custom_pages` | `GET`, `PUT`, `PATCH` e `DELETE /v4/workspace/custom_pages/{custom_page_id}`; `GET /v4/workspace/custom_pages` lista os conjuntos | | Azion CLI | `azion create custom-pages --file` | `azion describe custom-pages --custom-page-id` e `azion list custom-pages` | A CLI lê todos os campos do conjunto do arquivo JSON de `--file`. Para atribuir um conjunto, selecione-o no campo **Custom Page** da seção **Deployment Settings** do workload, envie seu ID em `strategy.attributes.custom_page` ou passe `--custom-page` para `azion create workload-deployment`. Um deployment sem conjunto contém `"custom_page": null`. A Azion não garante quando um conjunto atribuído começa a ser servido. Uma alteração no deployment de um workload leva vários minutos para chegar à infraestrutura distribuída da Azion, e as requisições podem receber a configuração anterior ou a atualizada enquanto ela se propaga. Na API v4, **Custom Pages** substitui Error Responses, as configurações de página de erro de uma aplicação da API v3. Cada campo da v3 tem um equivalente na v4: | Campo de Error Responses, API v3 | Campo de Custom Pages, API v4 | | -------------------------------- | ----------------------------------------------------- | | Status Code | **Page Code**, `code` | | Error Caching TTL | **Response TTL**, `ttl` | | URI | **Page Path (URI)**, `uri` | | Custom Status Code | **Response Custom Status Code**, `custom_status_code` | Os dois modelos localizam o arquivo da página de formas diferentes. Uma URI da v3 é anexada ao domínio da aplicação e buscada na origem nomeada em Set Origin. Uma `uri` da v4 é buscada no connector da página. Para uma aplicação que ainda roda na API v3, consulte [Error Responses](/pt-br/documentacao/plataforma/workloads/custom-pages/error-responses/). --- ## Campos do conjunto de custom pages Um conjunto de custom pages é uma lista nomeada de páginas. A API exige `name` e `pages`, e os outros campos são somente leitura, exceto `active`. No Console, a página **Create Custom Page** diz: "Create custom pages to handle errors and cache TTL based on the HTTP status code received from the Connectors." | Controle do Console | Campo da API | Tipo | Valores | Padrão | | --------------------- | ----------------- | -------------------------- | ----------------------------------------------------------------- | ----------------------- | | nenhum | `id` | integer | atribuído pela Azion, somente leitura | nenhum | | **Name** | `name` | string | 1 a 255 caracteres | obrigatório, sem padrão | | **Active** | `active` | boolean | `true`, `false` | `true` | | Tabela **Page Codes** | `pages` | array de objetos de página | ao menos uma página, cada uma descrita em Campos da página | obrigatório, sem padrão | | nenhum | `last_editor` | string | o email do último usuário que alterou o conjunto, somente leitura | nenhum | | nenhum | `last_modified` | string, date-time | somente leitura | nenhum | | nenhum | `created_at` | string, date-time | somente leitura | nenhum | | nenhum | `product_version` | string | somente leitura | `1.0` | O texto de ajuda de **Name** diz "Give a unique and descriptive name to identify the custom page." A tabela **Page Codes** lista uma linha por página, com as colunas **Page Status Code**, **Page Path (URI)**, **Custom Status Code** e **Response TTL**. Um conjunto sem página é recusado, na API e no Console. --- ## Campos da página Cada entrada de `pages` vincula um código de status a uma página. A página nomeia o connector que guarda o conteúdo, o caminho do conteúdo nesse connector, o tempo que a Azion o mantém em cache e um código de status opcional para a resposta. No Console, esses campos ficam nas seções **Status Configuration** e **Response Details** de uma página. | Controle do Console | Campo da API | Tipo | Valores | Padrão | | ------------------------------- | ------------------------------------ | ------------------ | -------------------------------------------------------------- | ----------------------- | | **Page Code** | `code` | string | `default` ou um dos códigos em Códigos de status, como `"404"` | obrigatório, sem padrão | | *Page Connector* | `page.type` | string | `page_connector` | `page_connector` | | **Connector** | `page.attributes.connector` | integer | o ID de um connector | obrigatório, sem padrão | | **Response TTL** | `page.attributes.ttl` | integer, segundos | 0 a 31.536.000 | `0` | | **Page Path (URI)** | `page.attributes.uri` | string, ou `null` | 1 a 250 caracteres | nenhum | | **Response Custom Status Code** | `page.attributes.custom_status_code` | integer, ou `null` | 100 a 599 | nenhum | Uma página age sobre o código de status que a Azion recebe do connector da aplicação. Quando esse código tem uma página no conjunto, o visitante recebe o conteúdo da página no lugar da resposta, sem redirecionamento, e o conteúdo pode ser armazenado em cache. O Console oferece dois tipos de página, *Page Connector* e *Page Default*. Com *Page Default*, o Console mostra os campos **Content Type** e **Response** no lugar dos campos do connector, e a API não tem formato documentado para esse tipo. `page.attributes.uri` é o caminho a partir do qual o connector da página entrega o conteúdo. Por exemplo, com o caminho `/myerrors/505.html` e um connector cujo endereço é `myconnector.azion.com`, a Azion busca e entrega o conteúdo de `myconnector.azion.com/myerrors/505.html`. `page.attributes.ttl` define quantos segundos a página de erro fica em cache antes que a Azion a atualize. Uma página de erro costuma ser estática e raramente muda, por isso a Azion recomenda um valor alto, que reduz o processamento feito pela sua origem. Para as configurações de expiração do cache da própria aplicação, consulte [Cache settings](/pt-br/documentacao/plataforma/applications/cache/cache-settings/#browser-cache). `page.attributes.custom_status_code` é o código de status que o visitante recebe no lugar do original. Por exemplo, uma página com `code` definido como `"403"` e `custom_status_code` definido como `404` responde a um `403` do connector com um `404`. --- ## Códigos de status O campo `code` aceita 22 códigos de status HTTP: 16 erros de cliente (4xx) e seis erros de servidor (5xx). Ele também aceita `default`, que o Console lista como *Default*. Para um código sem página própria, o texto de ajuda de **Page Codes** diz: "Codes tagged Azion serve the default Azion page; setting a custom page for one of them replaces it." A tabela descreve o que cada código significa quando o connector o retorna. | `code` | Status | O que a resposta do connector significa | | ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Bad Request | A requisição tem parâmetros inválidos ou não tem parâmetros obrigatórios. | | `401` | Unauthorized | A requisição não tem o header de autenticação que o servidor exige. | | `403` | Forbidden | O usuário não tem permissão para executar a operação. | | `404` | Not Found | O recurso solicitado não existe. | | `405` | Method Not Allowed | O método da requisição não pode ser aplicado à URL. | | `406` | Not Acceptable | A requisição não tem header `Accept`, ou o header pede um formato ou uma versão que o servidor não suporta. | | `408` | Request Timeout | A requisição chega mais devagar do que o servidor está preparado para esperar, então o servidor quer encerrar a conexão. Alguns navegadores, como Chrome, Firefox 27+ e IE9, abrem conexões antecipadamente para acelerar a navegação, o que torna essa resposta comum, e alguns servidores encerram a conexão sem enviá-la. | | `409` | Conflict | A requisição conflita com o estado do servidor, como uma requisição que cria um registro que já existe. | | `410` | Gone | O conteúdo foi excluído do servidor permanentemente, sem endereço de redirecionamento, então caches e links para ele devem ser removidos. A especificação HTTP o descreve para serviços promocionais limitados, e uma API não deve usá-lo para indicar quais recursos foram removidos. | | `411` | Length Required | O servidor exige um header `Content-Length`, e a requisição não tem nenhum. | | `414` | URI Too Long | A URI solicitada é mais longa do que o servidor aceita. | | `415` | Unsupported Media Type | O servidor não suporta o formato de mídia dos dados da requisição, então rejeita a requisição. | | `416` | Range Not Satisfiable | O servidor não consegue atender o valor do header `Range`, geralmente porque ele fica fora dos dados da URI de destino. | | `426` | Upgrade Required | O servidor recusa a requisição no protocolo atual e a aceita depois que o cliente troca de protocolo. Seu header `Upgrade` nomeia os protocolos que ele exige. | | `429` | Too Many Requests | A requisição excedeu um limite de operação e foi recusada por um tempo. O cliente deve aguardar antes de tentar novamente. | | `431` | Request Header Fields Too Large | Os headers da requisição são longos demais, ou a requisição envia cookies demais. | | `500` | Internal Server Error | Uma falha inesperada ocorreu enquanto o servidor processava a requisição. | | `501` | Not Implemented | O servidor não suporta o método da requisição. Os servidores devem suportar `GET` e `HEAD`, então não retornam esse código para esses dois métodos. | | `502` | Bad Gateway | O servidor, atuando como gateway, recebeu uma resposta inválida enquanto tratava a requisição. | | `503` | Service Unavailable | O servidor não está pronto para tratar a requisição, muitas vezes porque está sobrecarregado ou em manutenção. O código indica uma condição temporária: a resposta deve explicar o problema, levar um header `Retry-After` com o tempo estimado de recuperação e normalmente não é armazenada em cache. | | `504` | Gateway Timeout | O servidor, atuando como gateway, não recebeu uma resposta a tempo. | | `505` | HTTP Version Not Supported | O servidor não suporta a versão HTTP da requisição. | --- ## Corpo da requisição O corpo JSON abaixo cria um conjunto com uma página. Ele substitui um `404` do connector pelo documento que o connector serve em `/html` e responde com status `404`. O mesmo corpo funciona para `POST /v4/workspace/custom_pages` e para o arquivo de `azion create custom-pages --file`: ```json {"name": "my-custom-pages", "active": true, "pages": [ {"code": "404", "page": {"type": "page_connector", "attributes": {"connector": , "ttl": 0, "uri": "/html", "custom_status_code": 404}}} ]} ``` Envie-o com a CLI, com o corpo salvo como `cp.json`: ```bash azion create custom-pages --file cp.json ``` O comando imprime o ID do novo conjunto: ```text Created Custom Page with ID ``` `azion list custom-pages --details` lista o conjunto: ```text ID NAME ACTIVE LAST EDITOR LAST MODIFIED my-custom-pages true 2026-01-01 12:00:00.000000 +0000 UTC ``` `azion describe custom-pages --custom-page-id --format json` retorna o conjunto como a API o armazena, com cada atributo de página como enviado: ```json { "active": true, "created_at": "2026-01-01T12:00:00.00000Z", "id": , "is_versioned": false, "last_editor": "", "last_modified": "2026-01-01T12:00:00.000000Z", "name": "my-custom-pages", "pages": [ { "code": "404", "page": { "attributes": { "connector": , "custom_status_code": 404, "ttl": 0, "uri": "/html" }, "type": "page_connector" } } ], "product_version": "1.0", "version": null, "version_id": null, "version_state": null } ``` O conjunto só é servido depois que o deployment de um workload o nomeia. A CLI o atribui ao criar o deployment: ```bash azion create workload-deployment \ --workload-id \ --name my-deployment \ --application-id \ --custom-page \ --strategy-type default \ --active true \ --current true ``` O comando imprime o ID do novo deployment: ```text Created Workload Deployment with ID ``` Depois que o deployment se propaga, uma requisição cujo connector responde `404` recebe o conteúdo da página no lugar da resposta. A resposta mantém o status `404`, de `custom_status_code`, e não leva header `Location`, então o cliente não é redirecionado: ```bash curl -s -D - https:///status/404 ``` A resposta começa com a linha de status e o documento do caminho `/html` do connector: ```text HTTP/2 404 content-type: text/html; charset=utf-8

Herman Melville - Moby-Dick

``` --- ## Erros A API recusa um conjunto com a lista `pages` vazia, e o Console se recusa a salvar um. A CLI imprime a mensagem da API dentro de `Error: Failed to create Custom Page: [...]`, seguida de `Check your settings and try again. If the error persists, contact Azion support`. | Mensagem | Causa | O que fazer | | --------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- | | `Ensure this field has at least 1 elements.` | A requisição envia `"pages": []`. | Adicione ao menos uma página a `pages`. | | `You must have at least one custom page code` | O formulário do Console não tem página na tabela **Page Codes**. | Adicione um código de página antes de salvar o conjunto. | --- ## Recursos relacionados - [Primeiros passos com Custom Pages](/pt-br/documentacao/plataforma/workloads/custom-pages/primeiros-passos.md): Crie um conjunto de custom pages, atribua-o no deployment de um workload e veja uma página substituir um erro. - [Configurações de workload](/pt-br/documentacao/plataforma/workloads/configuracoes.md): Cada campo de um workload e do deployment que atribui sua aplicação, seu firewall e seu conjunto de custom pages. - [Error Responses](/pt-br/documentacao/plataforma/workloads/custom-pages/error-responses.md): As configurações de página de erro de uma aplicação da API v3, para contas que ainda rodam na API v3. - [Como Workloads funciona](/pt-br/documentacao/plataforma/workloads/como-funciona.md): O caminho que uma requisição percorre de um domínio, pelo workload, até sua aplicação e seu connector.