Erros da aplicação

GET

apps

{id}

analytics

errors

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"

{
  "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
      }
    ]
  }
}

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.

string

obrigatório

O ID da aplicação. Se ela pertencer a um workspace, informe o ID dele no query parameter 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.

string

Início da janela (ISO 8601). Padrão: 24 horas antes de end.

string

Fim da janela (ISO 8601). Padrão: agora. Não pode estar no futuro.

boolean

padrão:"false"

Envia também o período anterior, do mesmo tamanho e logo antes da janela, em previous. Padrão false.

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.

boolean

padrão:"false"

Conta 4xx como erro também, em errors, error_rate, paths e statuses. Padrão false.

integer

padrão:"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).

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.

string

País do visitante, ISO 3166-1 alfa-2 (BR).

string

Código IATA da localização de borda que respondeu (GRU).

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.

string

Caminho da requisição, sem a query string. É um prefixo: /api casa com /api, /api/users e /apix.

string

Método HTTP (GET, POST…).

string

Status HTTP que o visitante recebeu (404), ou uma classe: 2xx, 3xx, 4xx ou 5xx.

string

Versão do HTTP: HTTP/1.1, HTTP/2 ou HTTP/3.

string

Tipo de dispositivo: desktop, mobile ou tablet.

string

Sistema operacional do visitante (Windows, iOS…).

string

Navegador do visitante (Chrome, Safari…).

string

Host da página que levou à requisição (google.com). (none) é uma visita direta, sem referer.

string

Número do sistema autônomo da rede do visitante (28573).

string

Endereço IP do visitante.

string

Tipo de conteúdo respondido (html, json, css, js, png…).

string

Se a borda respondeu do cache: hit, miss, dynamic, bypass, expired, revalidated…

string

Categoria de um bot verificado (Search Engine Crawler…). (none) é um visitante que não é um bot verificado.

Resposta

object

Mostrar Toggle object

string

Início da janela realmente lida (ISO 8601). Pode ser arredondado em relação ao que você enviou.

string

Fim da janela realmente lida (ISO 8601).

string[]

Hostnames que foram lidos: o subdomínio da aplicação e seus domínios ativos.

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.

boolean

true quando o tráfego é alto o bastante para que os números sejam estimados a partir de uma amostra.

boolean

true quando os dados mais recentes não puderam ser lidos e esta é uma resposta anterior. Veja generated_at.

string

Quando os dados foram lidos (ISO 8601).

integer

Quantos dias para trás o plano do dono da aplicação consegue ler.

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.

boolean

Se 4xx contou como erro nesta resposta.

object | null

Totais da janela. null quando não houve requisição na janela. requests, errors, error_rate, errors_4xx, errors_5xx.

object[]

Pontos da série no tempo; time é o início de cada ponto, com requests, errors_4xx e errors_5xx.

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.

object[]

Caminhos com mais erros, maior errors primeiro. value é o caminho; envie-o como o filtro path.

object[]

Como os erros se distribuem pelos códigos de status, maior requests primeiro. value é o status, como 502.

Campos de summary:

integer

Requisições respondidas.

integer

errors_5xx, mais errors_4xx com include_4xx=true.

number

errors / requests, de 0 a 1.

integer

Requisições respondidas com status 4xx.

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.

{
  "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
      }
    ]
  }
}

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.
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.

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.

Última modificação em 3 de novembro de 2026

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"

{
  "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
      }
    ]
  }
}

Visão geral

Endpoints

Filtros

Resposta

Observações

Respostas de erro

​Filtros

​Resposta

​Observações

​Respostas de erro

Filtros

Resposta

Observações

Respostas de erro