# Errors

> For AI agents: a documentation index is available at [https://heirpros.com/llms.txt](https://heirpros.com/llms.txt). This page is also available as markdown at [https://heirpros.com/developers/errors.md](https://heirpros.com/developers/errors.md).

Errors return JSON with a code and a plain-English message.

## Error format

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are missing or not valid. unknown_heirs: Must be between 1 and 25.",
    "details": [ { "field": "unknown_heirs", "message": "Must be between 1 and 25." } ]
  }
}
```

`details` is only present for `validation_failed`. It lists each field that needs fixing.

## Error codes

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_json` | The body is not valid JSON. |
| 401 | `missing_api_key / invalid_api_key` | No API key was sent, or the key is not valid. |
| 405 | `method_not_allowed` | Wrong HTTP method. |
| 413 | `body_too_large` | The body is over 10 KB. |
| 422 | `validation_failed` | A field is missing or not valid. The message names each field. |
| 503 | `not_configured` | The API is temporarily unavailable. |

## Retrying

Fix the request before retrying a `4xx` error. A `503` can be retried after a short wait.
