---
title: Rate limits and errors
description: How /v1 throttles requests, and what every error response looks like.
order: 3
---

## Rate limits

Every `/v1` request - reads included, not just mutations - is rate-limited per API key: a burst of
**20 requests**, refilling at **1 every 200ms** (5/sec sustained). The limit is keyed by the key
itself, not by IP address, so requests from a shared CI runner or NAT gateway don't get lumped
together with anyone else's traffic.

A request over the limit gets:

```http
HTTP/1.1 429 Too Many Requests
```

Back off and retry - there's currently no `max_api_keys`-style ceiling on how many keys an org can
mint, so if 20 requests/burst is genuinely too tight for your use case, consider splitting work
across a second key rather than hammering one.

## Errors

Every error response is a JSON object with a single `error` field:

```json
{ "error": "unauthorized" }
```

| Status | Meaning |
| --- | --- |
| `400` | The request body failed validation - `error` describes what's wrong. |
| `401` | Missing, malformed, or revoked API key. |
| `403` | Either a `read_only` key attempted a mutation, or the org's plan doesn't include API access (Business only). |
| `404` | No such resource in this org - or, for `/v1/incidents/{id}`, that id belongs to a maintenance window, not an incident (see [Incidents](/guides/incidents)). |
| `429` | Rate limited - see above. |
| `500`/`502` | An internal error. Safe to retry; nothing on your end caused it. |