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

# Understanding Incidents

> How UptimeIO confirms failures, opens and resolves incidents, and what you can do with them

An incident records a period when a monitored service is failing or not meeting expectations. UptimeIO opens an incident only after a failure has been confirmed from several probe locations, so a single network glitch does not page you.

## How an incident is opened

<Steps>
  <Step title="A check fails">
    A scheduled check fails from one probe location. **No incident yet**: it could be a transient problem.
  </Step>

  <Step title="Confirmation checks run">
    About one second after each failure, the check is repeated from a different probe location, up to three attempts in total.
  </Step>

  <Step title="Consensus is reached">
    An incident opens only when **several probe locations agree** that the target is failing. See [Probe locations](/monitors/probe-locations) for where checks run.

    If a confirmation check succeeds, the failure is treated as transient and no incident is opened.
  </Step>

  <Step title="Notifications go out">
    Every verified [notification destination](/notifications/overview) assigned to the monitor that has the "Monitor goes down" event enabled is alerted.
  </Step>
</Steps>

<Info>
  This applies whichever locations you select on a monitor. Selected locations decide where regular checks run; confirmation checks prefer them but use the other locations when needed, so the rule holds even with a single selected location.
</Info>

## How an incident is resolved

Recovery mirrors detection: **several locations must see the target succeed** before the incident resolves. This prevents flapping, where a service bounces between failing and passing and creates alert fatigue. When the incident resolves, destinations with the "Monitor recovers" event enabled are notified.

You can also resolve an incident manually from its page or with the API.

## Incident types

Each incident has a `type` that describes the cause:

| Type | Raised when |
| - | - |
| `timeout` | The target did not respond in time (also used for missed heartbeats). |
| `connection_error` | The connection could not be established. |
| `status_code` | The response status was not one of the expected codes. |
| `keyword_missing` | A keyword monitor did not find (or unexpectedly found) its keywords. |
| `dns_error` | DNS resolution failed. |
| `dns_validation_error` | DNS records did not match the expected values. |
| `ssl_error` | The TLS certificate is expired or invalid. |
| `slow_response` | Response time exceeded your threshold. |

### Slow response

Set `slow_response_threshold_ms` on an HTTP or keyword monitor to be told when responses are too slow.

* A slow-response incident is **separate** from a downtime incident: a monitor can be up and still have an open slow-response incident.
* It resolves when response time stays **below 80% of the threshold for 3 consecutive checks**. With a 2,000 ms threshold, that is under 1,600 ms for three checks in a row.

### SSL certificate problems

Certificate **expiry warnings** (30, 15, 7 and 1 days before expiry, whichever you selected) are sent to your notification destinations and do **not** create an incident. An **expired or invalid** certificate does open an `ssl_error` incident, which resolves automatically once a valid certificate is seen. See [Setting Up Alerts](/essentials/setting-up-alerts#certificate-and-domain-expiry-warnings).

## Statuses and severity

| Status | Meaning |
| - | - |
| `open` | The incident is active. |
| `acknowledged` | A team member has seen it and is working on it. |
| `resolved` | The service has recovered. |
| `closed` | Final state. No further changes. |

Allowed transitions: `open` to `acknowledged` or `resolved`; `acknowledged` to `resolved` or `closed`; `resolved` to `closed`.

Severity is one of `critical`, `major`, `minor` or `warning`.

## Reading an incident

Open **Incidents** in the sidebar and select an incident. The page shows:

| Section | What it tells you |
| - | - |
| Header and metadata | Title, type, severity, status, start time, duration and affected locations. |
| Timeline | What happened and when, including confirmation attempts and status changes. |
| Affected monitors | Which monitors the incident covers. |
| Notification delivery | For each notification sent: channel, and whether it was **Sent**, **Failed** or **Pending**. |
| Comments | Team discussion on the incident. |

The incident list can be filtered by status (`open`, `acknowledged`, `resolved`, `closed`), severity, and search text.

## Work with incidents through the API

List open incidents:

```bash theme={null}
curl "https://api.uptimeio.com/api/incidents?status=open" \
  -H "X-API-Key: YOUR_API_KEY"
```

Acknowledge one:

```bash theme={null}
curl -X POST https://api.uptimeio.com/api/incidents/INCIDENT_ID/acknowledge \
  -H "X-API-Key: YOUR_API_KEY"
```

See the [Incidents API](/api-reference/incidents/introduction) for every endpoint and field.

## Reduce false alarms

<AccordionGroup>
  <Accordion title="Set a realistic timeout" icon="clock">
    The maximum timeout is 60 seconds, and it must be shorter than the check interval. Use 10 to 15 seconds for fast APIs and up to 60 seconds for slow services. Timeouts that are too short cause failures that are not real.
  </Accordion>

  <Accordion title="Match the expected status codes" icon="check">
    The default accepts only `200`. If your endpoint returns `201`, `204` or a redirect status you rely on, add those codes.
  </Accordion>

  <Accordion title="Allow UptimeIO through your firewall" icon="shield">
    If a firewall or rate limiter blocks probes, allow this user agent:

    ```
    UptimeIO-Monitor/1.0 (+https://uptimeio.com/monitoring-bot)
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Setting Up Alerts" icon="bell" href="/essentials/setting-up-alerts">
    Choose who is notified
  </Card>

  <Card title="Reading Metrics" icon="chart-line" href="/essentials/reading-metrics">
    Uptime and response time
  </Card>

  <Card title="Creating Monitors" icon="plus" href="/essentials/creating-monitors">
    Monitor settings
  </Card>

  <Card title="Incidents API" icon="code" href="/api-reference/incidents/introduction">
    Automate incident handling
  </Card>
</CardGroup>


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