# Errors

Every error is a status code and one sentence in an error field. What each code means, and what to do.

Rookery for developers · Updated October 11, 2026 · https://userookery.com/developers/errors/

When something goes wrong, the API answers with a status code and a JSON body with one field, `error`, that says what happened in a sentence:

```json
{ "error": "This key doesn't have the \"write\" scope." }
```

The sentence is written for people, so you can show it or log it. Don't match on its exact words; they may get clearer. Use the status code.

## Status codes

| Code | What happened | What to do |
|---|---|---|
| `400` | Something in the request is missing or not allowed, or the body isn't valid JSON | Fix the request. The message names each field, like `body: Too small` |
| `401` | No key, or the key is wrong or revoked | Check the `Authorization: Bearer rk_…` header |
| `403` | The key doesn't have the scope this needs | Make a key with that scope. See [Keys and scopes](https://userookery.com/developers/keys-and-scopes/) |
| `404` | No such conversation, or one the key can't see | Check the id. Someone else's private inbox always answers `404` |
| `429` | More than 120 requests in a minute with this key | Wait a few seconds, then try again. See [Rate limits](https://userookery.com/developers/rate-limits/) |
| `500` | Something went wrong on our side | Try again shortly. If it keeps happening, write to hello@userookery.com |

## Bad input

A `400` for bad input lists every problem at once, separated by semicolons, each starting with the field:

```json
{ "error": "status: Invalid option: expected one of \"open\"|\"waiting\"|\"closed\"" }
```

Each endpoint's fields, with their limits, are in the [API reference](https://userookery.com/developers/reference/).

## Retrying

Retry a `429` or a `500`, and a timeout or dropped connection, after a short wait. Before retrying a request that creates something, like a note or a reply, read [Retries](https://userookery.com/developers/retries/): a retry can make a second one.