---
title: Errors and limits
description: Problem Details errors with stable codes, the per-IP rate limit, and the headers that come with them.
sidebar:
  order: 9
---

## Errors

Errors use [Problem Details](https://www.rfc-editor.org/rfc/rfc9457) (RFC 9457) with `Content-Type: application/problem+json`. The `type` URL ends in a stable code, which is repeated in `code`.

```json
{
  "type": "https://arxivv.org/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "Unknown paper 1706.99999",
  "instance": "/1706.99999.md",
  "code": "not-found"
}
```

| Code           | Status | Meaning                                                                       |
| -------------- | ------ | ----------------------------------------------------------------------------- |
| `invalid-id`   | 400    | The path looks like a paper route but does not contain a valid paper ID       |
| `not-found`    | 404    | No such paper, version, section, figure or asset (assets: not mirrored yet)   |
| `no-html`      | 422    | arXiv has no HTML for this version, so no tree can be built                   |
| `rate-limited` | 429    | Rate limit exceeded; see `Retry-After`                                        |
| `build-failed` | 500    | The tree could not be built, or another internal error                        |
| `upstream`     | 502    | arXiv returned an error or rate-limited us during a build, or was unreachable |

- Match on `code` (or the code in `type`), not on `title` or `detail`. Codes are stable within a [schema major](/json#compatibility).
- Error responses carry `X-Arxivv-Schema`, `Vary: Prefer` and `Cache-Control: no-store`.
- Drop-in routes return arXiv's own error responses unchanged. Only an unreachable arXiv becomes `502 upstream`.

## Rate limit

| Limit                  | Key       | Applies to                                                           |
| ---------------------- | --------- | -------------------------------------------------------------------- |
| 60 requests per minute | Client IP | Every request the Worker handles: our formats, drop-in proxy, `/mcp` |

When you exceed it:

```http
HTTP/2 429
Content-Type: application/problem+json
Retry-After: 60
Cache-Control: no-store

{
  "type": "https://arxivv.org/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests; retry in a minute",
  "instance": "/1706.03762.md",
  "code": "rate-limited"
}
```

- No sign-up or API key is needed.
- The limit is counted per Cloudflare location and is approximate.
- Responses served from Cloudflare's cache never reach the Worker, so they do not count.
- Requests to `https://arxivv.org/mcp` count like any other request.
- Need more? Get in touch; limits are configuration, not code.

## Headers

| Header               | On                                                        | Meaning                                         |
| -------------------- | --------------------------------------------------------- | ----------------------------------------------- |
| `Retry-After`        | `429` (`60`), `202` (`5`), pending inferred fields (`10`) | Seconds to wait before retrying                 |
| `X-Arxivv-Schema`    | Every paper response and error                            | Major schema version                            |
| `X-Arxivv-Version`   | Every paper response                                      | arXiv version served                            |
| `X-Arxivv-Quality`   | Paper responses with a built tree                         | Quality score                                   |
| `X-Arxivv-Source`    | Paper responses with a built tree                         | Tree source                                     |
| `Vary`               | Paper responses and errors                                | Always `Prefer`                                 |
| `Link`               | Unversioned paper responses                               | `rel="canonical"` versioned URL                 |
| `Cache-Tag`          | Unversioned paper responses                               | `paper:<id>`, purged when a new version appears |
| `Preference-Applied` | Responses that honoured `Prefer`                          | The applied preference                          |
| `Location`           | `202`                                                     | The requested URL, to poll                      |