> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.lemmy.be/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.lemmy.be/_mcp/server.

# Errors & status codes

Every response from the Lemmy API uses the same envelope, whether the request succeeds or
fails. Each response contains:

| Field           | Type             | Description                                                                                                                             |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `IsSuccess`     | boolean          | Whether the request succeeded.                                                                                                          |
| `ErrorMessages` | array of strings | Human-readable messages describing what went wrong. Empty when `IsSuccess` is `true`.                                                   |
| *payload*       | varies           | The requested data or created records. The field name depends on the endpoint — for example `CustomerGroups`, `Customers`, or `Orders`. |

## Checking for success

`IsSuccess` and the HTTP status code always agree, so you can rely on either:

* **`IsSuccess: true`** → HTTP **`200 OK`**, and `ErrorMessages` is empty.
* **`IsSuccess: false`** → HTTP **`400 Bad Request`**, and `ErrorMessages` explains why.

Always check `IsSuccess` (or the status code) before using the payload.

A successful response:

```json
{
  "IsSuccess": true,
  "ErrorMessages": [],
  "CustomerGroups": [
    { "Code": "RETAIL", "Description": "Retail customers", "Active": true }
  ]
}
```

A failed response:

```json
{
  "IsSuccess": false,
  "ErrorMessages": [
    "x-page-offset header is required"
  ]
}
```

## Status codes

| Status                      | Meaning               | When it happens                                                                        |
| --------------------------- | --------------------- | -------------------------------------------------------------------------------------- |
| `200 OK`                    | Success               | The request succeeded (`IsSuccess: true`).                                             |
| `400 Bad Request`           | Request rejected      | A validation or business error occurred (`IsSuccess: false`). See common causes below. |
| `401 Unauthorized`          | Authentication failed | Missing or invalid API key. See [Authentication](/authentication).                     |
| `500 Internal Server Error` | Server error          | The request body was malformed JSON, or an unexpected error occurred on the server.    |

## Common causes of a 400

* Missing `x-page-offset` or `x-page-limit` headers on a `GET` request — see [Pagination](/pagination).
* Missing or invalid required fields in a `POST` request body.
* Any other validation error — read `ErrorMessages` for the specifics.

## Handling errors

Check `IsSuccess` before trusting the payload, and surface `ErrorMessages` when something
goes wrong:

```python
response = requests.get(url, headers=headers)  # headers include x-api-key and x-company-id
body = response.json()

if not body["IsSuccess"]:
    raise RuntimeError("; ".join(body["ErrorMessages"]))

# Safe to use the payload
process(body)
```