> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Obter detalhamento de erros na borda

> Conte os erros na borda por status, caminho, método e horário com GET /v2/apps/{app_id}/network/errors. Só 5xx por padrão; include_4xx=true soma os 4xx.

Retorna contagens agregadas de erros servidos na borda da aplicação em uma janela de tempo, agrupados por código de status, intervalo temporal, caminho da requisição e método HTTP. Por padrão somente respostas 5xx são incluídas; envie `include_4xx=true` para contar também as 4xx.

<Info>
  O cache miss compartilha um limite único de 20 requisições por 60 segundos por proprietário da aplicação, entre os endpoints de análise, erros, logs e performance. Respostas em cache não contam. Em períodos de alta demanda em toda a plataforma, o endpoint pode retornar os dados em cache mais recentes da janela solicitada. Retorna um resumo vazio quando não há erros no período ou quando a janela é anterior à data de criação da aplicação.
</Info>

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `apps:read`.

Como os erros 4xx incluem acessos causados pelo próprio cliente, como sondagens de scanners e links expirados, eles são excluídos por padrão; habilite `include_4xx=true` apenas quando precisar especificamente desse ruído, por exemplo ao auditar tráfego de bots. Códigos 5xx refletem problemas na borda ou na própria aplicação, então sempre são incluídos.

Este endpoint está disponível em todos os planos, assim como [Análise de rede](/pt-br/api-reference/endpoint/apps/network/analytics). Se você precisar de detalhes por requisição em vez de contagens agregadas, veja [Logs de rede](/pt-br/api-reference/endpoint/apps/network/logs) (apenas Pro e Enterprise). Para latência em vez de taxa de erro, veja [Performance de rede](/pt-br/api-reference/endpoint/apps/network/performance).

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL da sua aplicação no dashboard.
</ParamField>

<ParamField query="start" type="string" placeholder="Timestamp ISO 8601" required>
  Timestamp inicial em formato ISO 8601 para a janela de análise.
</ParamField>

<ParamField query="end" type="string" placeholder="Timestamp ISO 8601" required>
  Timestamp final em formato ISO 8601. Deve ser posterior ao `start`.
</ParamField>

<ParamField query="include_4xx" type="string" placeholder="false">
  Define se respostas 4xx devem ser incluídas junto das 5xx. Aceita `true` ou `false`. O padrão é `false`.
</ParamField>

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

<ResponseField name="response" type="object">
  Resumo agregado dos erros na janela analisada.

  <Expandable title="Alternar objeto response">
    <ResponseField name="summary" type="object">
      Totais agregados da janela.

      <Expandable title="Alternar objeto summary">
        <ResponseField name="total" type="integer">Total de respostas de erro na janela.</ResponseField>

        <ResponseField name="by_class" type="object">
          Totais separados por classe de status HTTP.

          <Expandable title="Alternar objeto by_class">
            <ResponseField name="4xx" type="integer">Total de respostas 4xx (preenchido apenas quando `include_4xx=true`).</ResponseField>
            <ResponseField name="5xx" type="integer">Total de respostas 5xx.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="by_status" type="array">
      Quantidade de requisições agrupadas por cada código de status HTTP observado.

      <Expandable title="Alternar item by_status">
        <ResponseField name="status" type="integer">Código de status HTTP (ex. `502`, `504`).</ResponseField>
        <ResponseField name="requests" type="integer">Total de requisições que retornaram este status.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="timeseries" type="array">
      Contagens distribuídas em intervalos temporais ao longo da janela.

      <Expandable title="Alternar item timeseries">
        <ResponseField name="date" type="string">Timestamp inicial do intervalo, em formato ISO 8601.</ResponseField>
        <ResponseField name="buckets" type="object">Objeto cujas chaves são códigos de status HTTP, com a contagem observada no intervalo.</ResponseField>
        <ResponseField name="total" type="integer">Total de erros observados no intervalo.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="top_paths" type="array">
      Caminhos que produziram mais erros na janela.

      <Expandable title="Alternar item top_paths">
        <ResponseField name="path" type="string">Caminho da requisição.</ResponseField>
        <ResponseField name="method" type="string">Método HTTP.</ResponseField>
        <ResponseField name="total" type="integer">Total de erros para este caminho/método.</ResponseField>
        <ResponseField name="by_status" type="object">Contagens por código de status HTTP observado para este caminho/método.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="by_method" type="array">
      Totais agregados de erros agrupados por método HTTP.

      <Expandable title="Alternar item by_method">
        <ResponseField name="method" type="string">Método HTTP.</ResponseField>
        <ResponseField name="total" type="integer">Total de erros para este método.</ResponseField>
        <ResponseField name="by_status" type="object">Contagens por código de status HTTP observado para este método.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
    "status": "success",
    "response": {
      "summary": {
        "total": 42,
        "by_class": {
          "4xx": 0,
          "5xx": 42
        }
      },
      "by_status": [
        { "status": 502, "requests": 30 },
        { "status": 504, "requests": 12 }
      ],
      "timeseries": [
        {
          "date": "2025-12-01T12:00:00.000Z",
          "buckets": { "502": 5, "504": 2 },
          "total": 7
        }
      ],
      "top_paths": [
        {
          "path": "/api/users",
          "method": "GET",
          "total": 18,
          "by_status": { "502": 15, "504": 3 }
        }
      ],
      "by_method": [
        {
          "method": "GET",
          "total": 30,
          "by_status": { "502": 22, "504": 8 }
        }
      ]
    }
  }
  ```
</ResponseExample>

## Erros comuns

| Código | HTTP | Significado |
| - | - | - |
| `INVALID_TIME_RANGE` | 400 | `start`/`end` estão ausentes, malformados ou invertem o intervalo de tempo. |
| `RATE_LIMITED` | 429 | O limite compartilhado de cache misses foi atingido. Aguarde e tente novamente. |
| `UNABLE_TO_FETCH_ERRORS` | 500 | Falha ao obter os dados de erro do provedor de edge. |
| `ANALYTICS_BUSY` | 503 | As análises de borda estão temporariamente ocupadas. Tente novamente em um minuto. |

## Relacionados

* CLI: [`squarecloud app network errors`](/pt-br/cli-reference/edge-analytics#squarecloud-app-network-errors)
* SDKs: [`api.apps.network.errors()`](/pt-br/sdks/js/network) (JavaScript), [`client.apps.network.errors()`](/pt-br/sdks/py/network) (Python), [`c.Apps.Network.Errors()`](/pt-br/sdks/go/network) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.