> For the complete documentation index, see [llms.txt](https://cjay-1.gitbook.io/cjay-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cjay-1.gitbook.io/cjay-docs/contracts/errors.md).

# Error codes

The contract returns a `#[contracterror]` enum. Each variant is a stable `u32`. Codes are never reordered or reused, so off-chain clients can match on the number.

| Code | Name                  | Meaning                                                                       | Typically from                                                                     |
| ---- | --------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 1    | `NotFound`            | The plan or a sub-record (approval set, claim) does not exist.                | `get_legacy`, `get_claim`, `claim_assets`                                          |
| 2    | `NotAuthorized`       | Caller is not permitted to perform this action.                               | reserved / auth paths                                                              |
| 3    | `AlreadyApproved`     | This guardian has already approved this plan.                                 | `approve_guardian`                                                                 |
| 4    | `NotGuardian`         | Caller is not in the plan's guardian set.                                     | `approve_guardian`                                                                 |
| 5    | `ThresholdNotMet`     | Approvals have not reached the threshold.                                     | release-path checks                                                                |
| 6    | `InvalidShares`       | Beneficiary shares are empty or do not sum to `10_000` bps.                   | `create_legacy`                                                                    |
| 7    | `AlreadyClaimed`      | This beneficiary already withdrew their portion.                              | `claim_assets`                                                                     |
| 8    | `InvalidStatus`       | The plan is not in the right state for this call.                             | `deposit`, `approve_guardian`, `finalize_release`, `claim_assets`, `cancel_legacy` |
| 9    | `NothingToClaim`      | The caller's allocation is zero or missing.                                   | `claim_assets`                                                                     |
| 10   | `InvalidInput`        | A supplied value (threshold, amount, bps multiplication overflow) is invalid. | `create_legacy`, `finalize_release`                                                |
| 11   | `AlreadyFunded`       | `deposit` called on a plan that is already funded.                            | `deposit`                                                                          |
| 12   | `NotFunded`           | An action needing deposited funds ran before `deposit`.                       | `finalize_release`                                                                 |
| 13   | `InsufficientBalance` | The contract's live token balance is below `total_amount`.                    | `finalize_release`                                                                 |
| 14   | `DuplicateAddress`    | A guardian or beneficiary address appears more than once.                     | `create_legacy`                                                                    |

## Handling errors client-side

The API surfaces contract errors as HTTP responses; it never swallows them into a fake success. In TypeScript, decode the simulation error and map the code:

```ts
const MESSAGES: Record<number, string> = {
  3: "You've already confirmed this plan.",
  4: "You're not listed as a guardian for this plan.",
  7: "This portion has already been claimed.",
  8: "This plan isn't ready for that step yet.",
  11: "This plan is already funded.",
  13: "The plan isn't fully funded yet — try again once the deposit settles.",
  14: "That person is already on the plan.",
};
```

Unknown codes should fall back to a generic message and be logged with the raw code for triage.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cjay-1.gitbook.io/cjay-docs/contracts/errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.