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

# Error codes

Errors are returned as JSON with a stable shape and an HTTP status that tells you the category. Error responses never include stack traces or sensitive internal detail.

## Response shape

An error response carries (see the [OpenAPI spec](https://api.andromedainfra.pro/openapi.json) for exact field names):

* an **error code** (a stable string you can branch on),
* a **human-readable message** (safe to log; not for end users verbatim),
* and, where relevant, a **details** object (for example, which field failed validation) and a **request id** for support.

## HTTP status reference

| Status | Meaning                                                                         | What to do                                                                                                |
| ------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `400`  | Malformed request (bad JSON, missing required field)                            | Fix the request body or parameters                                                                        |
| `401`  | Missing or unknown API key                                                      | Send a valid `X-Api-Key`                                                                                  |
| `402`  | Quota exhausted                                                                 | Top up or wait for the quota window to roll; see [Quotas & rate limits](/hub/andromeda/pricing/quotas.md) |
| `403`  | Key lacks the required scope, or source IP not in the key's allowlist           | Use a key with the right scope, or call from an allowed IP                                                |
| `404`  | Resource not found (unknown dWallet, policy, session, signature)                | Check the identifier                                                                                      |
| `409`  | Conflict (a competing change, a session in the wrong state)                     | Re-read state and retry the appropriate step                                                              |
| `413`  | Request body too large                                                          | Reduce the payload (for example, smaller batches)                                                         |
| `422`  | Idempotency-Key reused with a different body, or a semantically invalid request | Use a new idempotency key for a new operation; fix the body                                               |
| `429`  | Rate limit exceeded                                                             | Back off; honour the `Retry-After` header                                                                 |
| `5xx`  | Server-side or upstream engine error                                            | Retry with backoff; if it persists, contact support with the request id                                   |

## Validation errors

Input is validated at the boundary. A validation failure returns `400` (or `422` for semantic problems) with a `details` object pointing at the offending field, so you can surface a precise message.

## Engine and on-chain errors

Some errors originate in the MPC or FHE engine, or in an on-chain program (a policy rejecting a signature, a precompile check failing). These are surfaced with a clear code and message; the underlying program error is summarised, not dumped. For policy rejections, [Dry-run / Simulate](/hub/andromeda/guides/simulate.md) tells you which check failed.

## Retrying safely

For anything mutating, retry with the same `Idempotency-Key` you used originally. That way a retry after a transient `5xx` or a dropped connection runs the operation at most once. See [Idempotency keys](/hub/andromeda/guides/idempotency.md).


---

# 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:

```
GET https://shinkalabs.gitbook.io/hub/andromeda/api-reference/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.