# Errors

> Every error is an RFC 9457 problem with a stable code and a page that explains the fix.

When a request fails, the API answers with an HTTP status and a body in the
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) format, `Content-Type: application/problem+json`:

```json
{
  "type": "https://getrefract.app/developers/errors/insufficient-scope",
  "title": "The credential does not grant the scope this endpoint needs.",
  "status": 403,
  "code": "INSUFFICIENT_SCOPE",
  "request_id": "6f1c9e2a-…"
}
```

- `code` is stable: branch on it, not on `title`, which can be reworded.
- `type` is the page that explains the error. Open it in a browser.
- `request_id` identifies your request in our logs. Quote it when you contact us.
- An invalid parameter adds `errors`, one entry per parameter:

  ```json
  "errors": [{ "detail": "Invalid option: expected one of …", "parameter": "status" }]
  ```

## Codes

| Status | Code | What to do |
|---|---|---|
| 400 | [`INVALID_REQUEST`](/developers/errors/invalid-request) | Fix the parameter named in `errors`. |
| 400 | [`INVALID_CURSOR`](/developers/errors/invalid-cursor) | Start again from the first page. |
| 401 | [`INVALID_TOKEN`](/developers/errors/invalid-token) | Send a valid key or token, or refresh it. |
| 403 | [`INSUFFICIENT_SCOPE`](/developers/errors/insufficient-scope) | Ask the member for the missing scope. |
| 404 | [`NOT_FOUND`](/developers/errors/not-found) | Check the id, or the path. |
| 422 | [`SMART_LIST_UNSUPPORTED`](/developers/errors/smart-list-unsupported) | Skip smart lists' titles for now. |
| 429 | [`RATE_LIMITED`](/developers/errors/rate-limited) | Wait the seconds in `Retry-After`. |
| 503 | [`UNAVAILABLE`](/developers/errors/unavailable) | Retry after the delay in `Retry-After`. |
| 500 | [`SERVER_ERROR`](/developers/errors/server-error) | Retry later; tell us the `request_id` if it lasts. |

A status the table does not list comes with `type: "about:blank"`: its meaning is the HTTP status itself.