> ## Documentation Index > Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Erros da aplicação > Retorna os erros 5xx do site de uma aplicação, e 4xx se pedido: totais, série no tempo, as rotas que mais falham e a divisão por status. Retorna os erros do site de uma aplicação: o total e a taxa, uma série no tempo, os caminhos que mais falham e como os erros se distribuem pelos códigos de status. Por padrão só 5xx conta como erro, porque 4xx é ruidoso (em geral bots e scanners); envie `include_4xx=true` para contá-lo também. São os dados de [Erros](https://docs.vertracloud.app/pt-br/web-analytics/errors.md). **id** `string` *required* O ID da aplicação. Se ela pertencer a um workspace, informe o ID dele no query parameter `workspace_id`. **workspace\_id** `string` Se a aplicação pertencer a um workspace, o ID do workspace. Obrigatório para membros do workspace que agem sobre uma aplicação que não lhes pertence. **start** `string` Início da janela (ISO 8601). Padrão: 24 horas antes de `end`. **end** `string` Fim da janela (ISO 8601). Padrão: agora. Não pode estar no futuro. **compare** `boolean` (default: false) Envia também o período anterior, do mesmo tamanho e logo antes da janela, em `previous`. Padrão `false`. **compare\_start** `string` Início do período a comparar (ISO 8601). O período comparado tem o mesmo tamanho da janela (`end` menos `start`) e começa aqui; `previous.start` e `previous.end` na resposta mostram qual foi. Implica `compare=true` e não pode ser enviado com `compare=false`. Sem ele, `compare=true` compara com o período logo antes da janela. **include\_4xx** `boolean` (default: false) Conta 4xx como erro também, em `errors`, `error_rate`, `paths` e `statuses`. Padrão `false`. **limit** `integer` (default: 10) Entradas em `paths` e `statuses`, de 1 a 25. Padrão 10. A janela tem no máximo 30 dias e não pode começar antes do histórico do plano (7 ou 30 dias, veja [Planos e limites](https://docs.vertracloud.app/pt-br/plans-and-limits.md)). ### Filtros Cada dimensão abaixo também é um filtro, e todos podem ser combinados: cada um restringe todas as partes da resposta. Cada filtro recebe **um valor**, exatamente como aparece numa entrada de breakdown ou numa requisição do log, então um valor lido numa resposta pode ser enviado de volta sem mudar. Envie `(none)` para manter só as requisições que não têm nada na dimensão. **country** `string` País do visitante, ISO 3166-1 alfa-2 (`BR`). **edge\_location** `string` Código IATA da localização de borda que respondeu (`GRU`). **host** `string` Hostname que o visitante pediu: o subdomínio da aplicação ou um dos seus domínios. Só são aceitos hosts da aplicação. **path** `string` Caminho da requisição, sem a query string. É um prefixo: `/api` casa com `/api`, `/api/users` e `/apix`. **method** `string` Método HTTP (`GET`, `POST`...). **status** `string` Status HTTP que o visitante recebeu (`404`), ou uma classe: `2xx`, `3xx`, `4xx` ou `5xx`. **protocol** `string` Versão do HTTP: `HTTP/1.1`, `HTTP/2` ou `HTTP/3`. **device** `string` Tipo de dispositivo: `desktop`, `mobile` ou `tablet`. **os** `string` Sistema operacional do visitante (`Windows`, `iOS`...). **browser** `string` Navegador do visitante (`Chrome`, `Safari`...). **referer** `string` Host da página que levou à requisição (`google.com`). `(none)` é uma visita direta, sem referer. **asn** `string` Número do sistema autônomo da rede do visitante (`28573`). **ip** `string` Endereço IP do visitante. **content\_type** `string` Tipo de conteúdo respondido (`html`, `json`, `css`, `js`, `png`...). **cache\_status** `string` Se a borda respondeu do cache: `hit`, `miss`, `dynamic`, `bypass`, `expired`, `revalidated`... **bot** `string` Categoria de um bot verificado (`Search Engine Crawler`...). `(none)` é um visitante que não é um bot verificado. ### Resposta **response** `object` **Toggle object** **start** `string` Início da janela realmente lida (ISO 8601). Pode ser arredondado em relação ao que você enviou. **end** `string` Fim da janela realmente lida (ISO 8601). **hosts** `string[]` Hostnames que foram lidos: o subdomínio da aplicação e seus domínios ativos. **web\_published** `boolean` `false` quando a aplicação não tem site publicado. A resposta é então um estado vazio, não um erro: `hosts` vem vazio e os dados também. **sampled** `boolean` `true` quando o tráfego é alto o bastante para que os números sejam estimados a partir de uma amostra. **stale** `boolean` `true` quando os dados mais recentes não puderam ser lidos e esta é uma resposta anterior. Veja `generated_at`. **generated\_at** `string` Quando os dados foram lidos (ISO 8601). **history\_days** `integer` Quantos dias para trás o plano do dono da aplicação consegue ler. **interval** `string` Tamanho de cada ponto de `series`: `1m`, `5m`, `15m` ou `1h`. A API escolhe pelo tamanho da janela: quanto menor a janela, mais finos os pontos. **include\_4xx** `boolean` Se 4xx contou como erro nesta resposta. **summary** `object | null` Totais da janela. `null` quando não houve requisição na janela. `requests`, `errors`, `error_rate`, `errors_4xx`, `errors_5xx`. **series** `object[]` Pontos da série no tempo; `time` é o início de cada ponto, com `requests`, `errors_4xx` e `errors_5xx`. **previous** `object | null` O período anterior, só com `compare=true`; caso contrário `null`. Tem `start`, `end`, um `summary` (`null` quando não houve requisição nele) e uma `series` com o mesmo `interval` e o mesmo número de pontos da atual, na mesma ordem. **paths** `object[]` Caminhos com mais erros, maior `errors` primeiro. `value` é o caminho; envie-o como o filtro `path`. **statuses** `object[]` Como os erros se distribuem pelos códigos de status, maior `requests` primeiro. `value` é o status, como `502`. Campos de `summary`: **requests** `integer` Requisições respondidas. **errors** `integer` `errors_5xx`, mais `errors_4xx` com `include_4xx=true`. **error\_rate** `number` `errors / requests`, de 0 a 1. **errors\_4xx** `integer` Requisições respondidas com status 4xx. **errors\_5xx** `integer` Requisições respondidas com status 5xx. Entradas de `paths`: `value`, `requests`, `errors` (conta 4xx só com `include_4xx=true`) e `error_rate`. Entradas de `statuses`: `value`, `label`, `requests`, `visits` e `bytes`. ```json Response theme={null} { "response": { "start": "2026-11-02T18:00:00Z", "end": "2026-11-03T18:00:00Z", "hosts": [ "my-app.vertraweb.app", "www.example.com" ], "web_published": true, "sampled": false, "stale": false, "generated_at": "2026-11-03T18:01:12Z", "history_days": 7, "interval": "1h", "include_4xx": false, "summary": { "requests": 18420, "errors": 9, "error_rate": 0.0005, "errors_4xx": 214, "errors_5xx": 9 }, "series": [ { "time": "2026-11-02T18:00:00Z", "requests": 702, "errors_4xx": 8, "errors_5xx": 0 }, { "time": "2026-11-02T19:00:00Z", "requests": 731, "errors_4xx": 11, "errors_5xx": 3 } ], "previous": null, "paths": [ { "value": "/api/checkout", "requests": 412, "errors": 6, "error_rate": 0.0146 }, { "value": "/api/users", "requests": 2210, "errors": 3, "error_rate": 0.0014 } ], "statuses": [ { "value": "502", "label": null, "requests": 5, "visits": 0, "bytes": 2210 }, { "value": "500", "label": null, "requests": 3, "visits": 0, "bytes": 1880 }, { "value": "504", "label": null, "requests": 1, "visits": 0, "bytes": 420 } ] } } ``` ```bash cURL theme={null} curl -G "https://api.vertracloud.app/v1/apps/app-abc123def456/analytics/errors" \ -H "Authorization: Bearer YOUR_TOKEN" \ --data-urlencode "start=2026-11-02T18:00:00Z" \ --data-urlencode "end=2026-11-03T18:00:00Z" \ --data-urlencode "include_4xx=false" \ --data-urlencode "path=/api" \ --data-urlencode "limit=5" ``` ### Observações * Exige o escopo `apps:read` quando chamada com uma chave de API. Membros de workspace precisam de permissão para ler a aplicação. * Todos os planos. * **Amostragem.** Com tráfego alto os números são estimados a partir de uma amostra e `sampled` vem `true`. Veja [Amostragem e atraso](https://docs.vertracloud.app/pt-br/web-analytics/sampling-and-delay.md). * **Atraso.** Os dados se atualizam a cada cerca de 5 minutos, então as requisições mais novas podem levar alguns minutos para aparecer. Se os dados mais recentes não puderem ser lidos agora, uma resposta anterior pode voltar com `stale: true` (veja `generated_at`); caso contrário, a chamada falha com `ANALYTICS_BUSY`. * **Privacidade.** A Vertra Cloud não guarda nada sobre os visitantes; guarda apenas totais por app (contagens, visitas, bytes, taxas de erro e tempos de resposta) por até 31 dias, apagados com o app. Nenhum IP, caminho, query string ou user agent é guardado. `ip` e `query` voltam sem máscara; mascarar é uma escolha do cliente que os exibe. Veja [Privacidade](https://docs.vertracloud.app/pt-br/web-analytics/privacy.md). ### Respostas de erro | Status | Código | Quando | | - | - | - | | 401 | `AUTH_TOKEN_MISSING` / `API_KEY_INVALID` / `SESSION_REVOKED` | O header `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada. | | 403 | `API_KEY_IP_DENIED` / `API_KEY_SCOPE_DENIED` | A chave de API é usada de um IP fora da sua lista de permitidos, ou não tem o escopo `apps:read`. | | 403 | `ACCESS_DENIED` | A aplicação pertence a outra conta, ou você não tem a permissão de workspace para lê-la. | | 403 | `PLAN_REQUIRED` | A conta não tem plano ativo. | | 404 | `APP_NOT_FOUND` | A aplicação não existe. | | 400 | `VALIDATION_ERROR` | Um parâmetro falhou na validação, como `limit` fora do intervalo, `cursor` inválido ou data `start`/`end` malformada; `details.path` nomeia o campo. Também quando `compare_start` é malformado ou vem com `compare=false`. | | 400 | `INVALID_RANGE` | `start` é posterior a `end`, `end` está no futuro ou a janela passa de 30 dias. Também quando o período que começa em `compare_start` termina depois de `start`, o que sobreporia a janela. | | 400 | `ANALYTICS_RANGE_EXCEEDS_PLAN` | `start` é anterior ao que o plano consegue ler. `details.history_days` traz o limite em dias e `details.earliest` o `start` mais antigo aceito agora. Também quando `compare_start` é anterior ao que o plano consegue ler. | | 429 | `RATE_LIMIT_EXCEEDED` | Muitas consultas seguidas. `details.retry_after` informa a espera em segundos; o header `Retry-After` vem sempre junto. | | 503 | `ANALYTICS_BUSY` | Momento de alta demanda e sem resposta recente disponível para a consulta. Espere `details.retry_after` segundos e tente de novo. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.