> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3ringscapital.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error shape and how to handle each status.

Every error returns a consistent JSON shape under an `error` key:

```json theme={null}
{
  "error": {
    "type": "unbalanced_journal",
    "message": "Debits (25000000) do not equal credits (24000000).",
    "code": "journal.unbalanced",
    "param": "entries"
  }
}
```

* `type` — a stable, machine-readable category. Branch on this.
* `message` — a human-readable explanation. Safe to log; do not pattern-match on it.
* `code` — a dotted sub-code for finer handling.
* `param` — the offending field, when applicable.

## Status codes

| Status | Meaning | What to do |
| - | - | - |
| `400` | Malformed request | Fix the request shape. |
| `401` | Missing/invalid API key | Check the `Authorization` header. |
| `402` | Insufficient AI credits | Top up credits (categorization). |
| `404` | Resource not found | Check the ID and that it belongs to you. |
| `409` | Conflict (e.g. duplicate) | Safe to treat as already-done with idempotency. |
| `422` | Unprocessable (e.g. unbalanced journal) | Fix the business-rule violation. |
| `429` | Rate limited | Back off and retry with jitter. |
| `5xx` | Server error | Retry with backoff; the request may not have applied — reuse your idempotency key. |

> [!NOTE]
>
> Pair `429` and `5xx` handling with [idempotency keys](https://docs.3ringscapital.co/guides/idempotency.md) so retries never
> double-post.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.