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

# Errors

The API uses standard HTTP status codes: `2xx` for success, `4xx` for a problem with the request, `5xx` for a problem on our side. Every error answers a JSON:API error document with `Content-Type: application/vnd.api+json`.

## The error document

```json
{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "The page.size field must not be greater than 50.",
      "source": { "parameter": "page[size]" }
    }
  ],
  "jsonapi": { "version": "1.1" }
}
```

| Member             | Always present              | Meaning                                                                                        |
| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------- |
| `status`           | Yes                         | The HTTP status code, as a string                                                              |
| `title`            | Yes                         | A short summary of the kind of error                                                           |
| `detail`           | When there is a message     | What went wrong in this request, in English                                                    |
| `source.parameter` | Validation and query errors | The offending field or query parameter, in bracket form (`page[size]`, `filter[core_version]`) |

A validation failure lists one error object per problem, so a single response can carry several entries in `errors`.

## Status codes

| Code  | `title`                   | When                                                                                                                                                                                 |
| ----- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | `Invalid Query Parameter` | An unknown filter, sort or include. `source.parameter` is `filter`, `sort` or `include`, and `detail` lists the allowed values. See [Filtering and sorting](/filtering-and-sorting). |
| `401` | `Unauthenticated`         | The token is missing, malformed, unknown or expired. See [Authentication](/authentication).                                                                                          |
| `403` | `Forbidden`               | A read-only token tried to write, your role does not allow the action, or the organization's Public API is disabled or out of quota. See [Organizations](/organizations).            |
| `404` | `Not Found`               | The resource does not exist, or belongs to another organization.                                                                                                                     |
| `409` | `Error`                   | The request conflicts with the organization's state, for example creating backups with the storage quota exhausted.                                                                  |
| `422` | `Validation Error`        | A body field or query value is invalid, `page[size]` is above 50, or the query uses a parameter the API does not accept.                                                             |
| `429` | `Error`                   | Too many requests. See [Rate limits](/rate-limits).                                                                                                                                  |
| `500` | `Server Error`            | Something failed on our side. Retrying later is safe for reads.                                                                                                                      |

## Handling errors

* Branch on the HTTP status and on `status`, not on `detail`: the wording of `detail` can improve over time.
* Show `detail` to a person when it helps: it is written to be read.
* Use `source.parameter` to point at the field to fix.

> The error document and the status codes the API answers