> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/errors.md).

# Errors

Every error the API can return: the Problem Details envelope, how to handle it, and the full catalog of stable error codes.

Every non-2xx response — REST and GraphQL alike — speaks one error language. REST returns an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) Problem Details object; GraphQL carries the same `code` vocabulary in `errors[].extensions.code`.

```json
{
  "type": "https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/errors/escrow-not-found",
  "title": "Not Found",
  "status": 404,
  "code": "ESCROW_NOT_FOUND",
  "detail": "Escrow does not exist.",
  "instance": "/escrow/single-release/v2/fund-escrow",
  "traceId": "d0f1…"
}
```

### How to handle errors

* **Switch on `code`.** It is stable and never renamed. `detail` is human prose and may change without notice.
* **`type` is a link** to that code's page in this section.
* **`extensions` carries machine-readable context** where it helps: `extensions.errors[]` on validation failures, `extensions.restoreXdr` on `STELLAR_STATE_ARCHIVED`.
* **Include `traceId`** when reporting a problem — it correlates your request with the server logs.

## Escrow contract errors

Raised when the on-chain simulation of a build endpoint fails inside the escrow contract. They are grouped by the lifecycle phase where you will most likely hit them — note that a few codes can surface in more than one operation.

### Deploy, update & configuration

Invalid roles, milestones or properties when deploying or updating an escrow.

| Code                                               | Status | Summary                                                                        |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| `ESCROW_ADMIN_ADDRESS_CANNOT_BE_CHANGED`           | 422    | Admin address cannot be changed after initialization.                          |
| `ESCROW_ADMIN_ADDRESS_OVERLAPS_WITH_OTHER_ROLE`    | 422    | Admin address must not overlap with any other role.                            |
| `ESCROW_ALREADY_INITIALIZED`                       | 409    | Escrow is already initialized.                                                 |
| `ESCROW_AMOUNT_CANNOT_BE_ZERO`                     | 422    | Amount must be greater than zero.                                              |
| `ESCROW_APPROVERS_LIST_EMPTY`                      | 422    | roles.approvers must contain at least one address.                             |
| `ESCROW_DISPUTE_RESOLVERS_LIST_EMPTY`              | 422    | roles.dispute\_resolvers must contain at least one address.                    |
| `ESCROW_DISPUTE_RESOLVER_OVERLAPS_WITH_OTHER_ROLE` | 422    | A dispute resolver cannot also appear in another role.                         |
| `ESCROW_DUPLICATE_ADDRESS_IN_ROLE`                 | 422    | A role list contains duplicate addresses.                                      |
| `ESCROW_FLAGS_MUST_BE_FALSE`                       | 422    | Escrow flags (approved, disputed, released) must all be false for this action. |
| `ESCROW_HAS_FUNDS`                                 | 409    | Escrow still holds funds; action blocked.                                      |
| `ESCROW_INCOMPATIBLE_WASM_HASH`                    | 422    | Target contract is not an instance of the expected escrow type.                |
| `ESCROW_MILESTONE_APPROVED_CANT_CHANGE_PROPERTIES` | 409    | Escrow properties cannot be modified after a milestone approval.               |
| `ESCROW_NO_MILESTONE_DEFINED`                      | 422    | Escrow has no milestones defined.                                              |
| `ESCROW_PLATFORM_ADDRESS_CANNOT_BE_CHANGED`        | 422    | Platform address cannot be modified.                                           |
| `ESCROW_PLATFORM_FEE_TOO_HIGH`                     | 422    | Platform fee cannot exceed 99%.                                                |
| `ESCROW_PROPERTIES_MISMATCH`                       | 409    | Provided escrow properties do not match the on-chain state.                    |
| `ESCROW_RELEASE_SIGNERS_LIST_EMPTY`                | 422    | roles.release\_signers must contain at least one address.                      |
| `ESCROW_ROLE_LIMIT_EXCEEDED`                       | 422    | A role list exceeded its maximum size (5 addresses per list).                  |
| `ESCROW_SERVICE_PROVIDERS_LIST_EMPTY`              | 422    | roles.service\_providers must contain at least one address.                    |
| `ESCROW_STRING_TOO_LONG`                           | 422    | A String field exceeded its on-chain maximum length.                           |
| `ESCROW_TARGET_CANNOT_BE_ZERO`                     | 422    | A milestone approvals.target must be greater than zero.                        |
| `ESCROW_TARGET_EXCEEDS_APPROVERS`                  | 422    | A milestone approvals.target cannot exceed roles.approvers.length.             |
| `ESCROW_TOO_MANY_MILESTONES`                       | 422    | Too many milestones; the maximum is 50.                                        |
| `ESCROW_TOTAL_AMOUNT_CANNOT_BE_ZERO`               | 422    | Total amount cannot be zero.                                                   |

### Funding

| Code                                    | Status | Summary                                |
| --------------------------------------- | ------ | -------------------------------------- |
| `ESCROW_INSUFFICIENT_FUNDS_FOR_FUNDING` | 409    | Insufficient funds to fund the escrow. |
| `ESCROW_NOT_FUNDED`                     | 409    | Escrow has not been funded yet.        |

### Milestones & approvals

Changing milestone status, approving milestones, and managing the milestone list.

| Code                                             | Status | Summary                                                   |
| ------------------------------------------------ | ------ | --------------------------------------------------------- |
| `ESCROW_APPROVER_ALREADY_APPROVED_MILESTONE`     | 409    | This approver already approved this milestone.            |
| `ESCROW_BATCH_MILESTONE_APPROVE_EMPTY`           | 422    | approve\_milestones batch cannot be empty.                |
| `ESCROW_BATCH_MILESTONE_UPDATE_EMPTY`            | 422    | change\_milestone\_status batch cannot be empty.          |
| `ESCROW_BATCH_TOO_LARGE`                         | 422    | Milestone batch exceeded the maximum size of 50 entries.  |
| `ESCROW_DUPLICATE_MILESTONE_INDEX`               | 422    | Duplicate milestone indices are not allowed in the batch. |
| `ESCROW_EMPTY_MILESTONE_STATUS`                  | 422    | Milestone status cannot be empty.                         |
| `ESCROW_INVALID_MILESTONE_INDEX`                 | 422    | Milestone index is out of range.                          |
| `ESCROW_MILESTONE_HAS_ALREADY_BEEN_APPROVED`     | 409    | Milestone was already approved.                           |
| `ESCROW_MILESTONE_NOT_COMPLETED`                 | 409    | Milestone is not completed; action cannot proceed.        |
| `ESCROW_MILESTONE_NOT_FOUND`                     | 404    | Milestone does not exist.                                 |
| `ESCROW_MILESTONE_TO_APPROVE_DOES_NOT_EXIST`     | 404    | Milestone to approve does not exist.                      |
| `ESCROW_MILESTONE_TO_UPDATE_DOES_NOT_EXIST`      | 404    | Milestone to update does not exist.                       |
| `ESCROW_MILESTONE_UPDATE_NOT_ALLOWED_WITH_FUNDS` | 409    | Milestones cannot be edited while the escrow holds funds. |

### Disputes & resolution

Opening disputes and distributing funds when resolving them.

| Code                                                          | Status | Summary                                                     |
| ------------------------------------------------------------- | ------ | ----------------------------------------------------------- |
| `ESCROW_ALREADY_IN_DISPUTE`                                   | 409    | Escrow is already in dispute.                               |
| `ESCROW_ALREADY_RESOLVED`                                     | 409    | Escrow dispute is already resolved.                         |
| `ESCROW_AMOUNTS_TO_TRANSFER_SHOULD_BE_POSITIVE`               | 422    | Transfer amounts must be positive.                          |
| `ESCROW_APPROVER_OR_RECEIVER_FUNDS_LESS_THAN_ZERO`            | 422    | Approver or receiver funds cannot be negative.              |
| `ESCROW_BATCH_MILESTONE_DISPUTE_EMPTY`                        | 422    | dispute\_milestones requires at least one milestone index.  |
| `ESCROW_DISTRIBUTIONS_MUST_EQUAL_BALANCE`                     | 422    | Distributions must equal the total escrow balance.          |
| `ESCROW_INSUFFICIENT_FUNDS_FOR_RESOLUTION`                    | 409    | Insufficient funds to resolve the dispute.                  |
| `ESCROW_MILESTONE_ALREADY_DISPUTED`                           | 409    | Targeted milestone is already in dispute.                   |
| `ESCROW_MILESTONE_ALREADY_IN_DISPUTE`                         | 409    | Milestone is already in dispute.                            |
| `ESCROW_MILESTONE_ALREADY_RESOLVED`                           | 409    | Milestone dispute is already resolved.                      |
| `ESCROW_MILESTONE_NOT_IN_DISPUTE`                             | 409    | Milestone is not currently in dispute.                      |
| `ESCROW_MILESTONE_OPENED_FOR_DISPUTE_RESOLUTION`              | 409    | Milestone is opened for dispute resolution; action blocked. |
| `ESCROW_NOT_IN_DISPUTE`                                       | 409    | Escrow is not currently in dispute.                         |
| `ESCROW_OPENED_FOR_DISPUTE_RESOLUTION`                        | 409    | Escrow is opened for dispute resolution; action blocked.    |
| `ESCROW_RECEIVER_AND_APPROVER_FUNDS_NOT_EQUAL`                | 422    | Receiver and approver distributions do not match.           |
| `ESCROW_TOO_MANY_DISTRIBUTIONS`                               | 422    | Too many distributions; the maximum is 50.                  |
| `ESCROW_TOTAL_DISPUTE_FUNDS_MUST_NOT_EXCEED_MILESTONE_AMOUNT` | 422    | Total dispute funds cannot exceed the milestone amount.     |

### Release, withdraw & refunds

| Code                                                         | Status | Summary                                                  |
| ------------------------------------------------------------ | ------ | -------------------------------------------------------- |
| `ESCROW_ALREADY_RELEASED`                                    | 409    | Escrow funds were already released.                      |
| `ESCROW_BALANCE_NOT_ENOUGH_TO_SEND_EARNINGS`                 | 409    | Escrow balance is insufficient to release the earnings.  |
| `ESCROW_CANT_RELEASE_A_MILESTONE_IN_DISPUTE`                 | 409    | Cannot release a milestone that is in dispute.           |
| `ESCROW_INSUFFICIENT_APPROVER_FUNDS_FOR_COMMISSIONS`         | 409    | Approver has insufficient funds for commissions.         |
| `ESCROW_INSUFFICIENT_ESCROW_FUNDS_TO_MAKE_REFUND`            | 409    | Insufficient escrow funds to make the refund.            |
| `ESCROW_INSUFFICIENT_FUNDS_FOR_REFUND`                       | 409    | Insufficient funds for refund.                           |
| `ESCROW_INSUFFICIENT_SERVICE_PROVIDER_FUNDS_FOR_COMMISSIONS` | 409    | Service provider has insufficient funds for commissions. |
| `ESCROW_MILESTONE_ALREADY_RELEASED`                          | 409    | Milestone funds were already released.                   |
| `ESCROW_NOT_COMPLETED`                                       | 409    | Escrow has pending milestones; action cannot proceed.    |
| `ESCROW_NOT_FULLY_PROCESSED`                                 | 409    | Escrow has not been fully processed.                     |
| `ESCROW_RELEASE_MILESTONES_EMPTY`                            | 422    | release\_funds requires at least one milestone index.    |

### Roles: who can do what

The signing wallet does not hold the role the action requires. Check the escrow's roles with a read endpoint before building the transaction.

| Code                                                       | Status | Summary                                                        |
| ---------------------------------------------------------- | ------ | -------------------------------------------------------------- |
| `ESCROW_DISPUTE_RESOLVER_CANNOT_DISPUTE`                   | 403    | The dispute resolver cannot initiate a dispute.                |
| `ESCROW_DISPUTE_RESOLVER_CANNOT_DISPUTE_MILESTONE`         | 403    | The dispute resolver cannot initiate a dispute on a milestone. |
| `ESCROW_ONLY_ADMIN_CAN_EXECUTE`                            | 403    | Only the admin address can perform this action.                |
| `ESCROW_ONLY_APPROVER_CAN_CHANGE_MILESTONE_FLAG`           | 403    | Only the approver can change the milestone approval flag.      |
| `ESCROW_ONLY_DISPUTE_RESOLVER_CAN_EXECUTE`                 | 403    | Only the dispute resolver can perform this action.             |
| `ESCROW_ONLY_PLATFORM_ADDRESS_CAN_EXECUTE`                 | 403    | Only the platform address can perform this action.             |
| `ESCROW_ONLY_RELEASE_SIGNER_CAN_RELEASE`                   | 403    | Only the designated release signer can release funds.          |
| `ESCROW_ONLY_SERVICE_PROVIDER_CAN_CHANGE_MILESTONE_STATUS` | 403    | Only the service provider can change a milestone status.       |
| `ESCROW_SIGNER_MUST_BE_APPROVER_AND_RELEASE_SIGNER`        | 403    | The signer must be in both approvers and release\_signers.     |
| `ESCROW_UNAUTHORIZED_APPROVER`                             | 403    | Caller is not in roles.approvers.                              |
| `ESCROW_UNAUTHORIZED_TO_CHANGE_DISPUTE_FLAG`               | 403    | Caller is not authorized to change the dispute flag.           |

### Lookup & arithmetic

Cross-cutting: the escrow does not exist, or an amount overflowed on-chain.

| Code                                | Status | Summary                                                 |
| ----------------------------------- | ------ | ------------------------------------------------------- |
| `ESCROW_DIVISION_ERROR`             | 500    | Arithmetic division error while processing the escrow.  |
| `ESCROW_NOT_FOUND`                  | 404    | Escrow does not exist.                                  |
| `ESCROW_OVERFLOW`                   | 500    | Arithmetic overflow while processing the escrow.        |
| `ESCROW_REENTRANCY`                 | 500    | Reentrant call detected.                                |
| `ESCROW_TOO_MANY_ESCROWS_REQUESTED` | 422    | Too many escrows requested; the maximum is 20 per call. |
| `ESCROW_UNDERFLOW`                  | 500    | Arithmetic underflow while processing the escrow.       |

## API errors

Raised by the API itself before anything touches the chain.

### Authentication, API keys & sessions

| Code                                   | Status | Summary                                                     |
| -------------------------------------- | ------ | ----------------------------------------------------------- |
| `API_KEY_LIMIT_REACHED`                | 409    | You have reached the maximum number of active API keys.     |
| `AUTH_BOOTSTRAP_ALREADY_DONE`          | 409    | An admin already exists.                                    |
| `AUTH_BOOTSTRAP_EMAIL_TAKEN`           | 409    | A user with that email already exists.                      |
| `AUTH_BOOTSTRAP_INVALID_SECRET`        | 401    | Invalid bootstrap secret.                                   |
| `AUTH_BOOTSTRAP_SECRET_NOT_CONFIGURED` | 422    | Bootstrap is disabled on this deployment.                   |
| `AUTH_CREDENTIAL_MISSING`              | 401    | The request carries no API key or session token.            |
| `AUTH_INSUFFICIENT_ROLE`               | 403    | The credential does not have permission for this operation. |
| `AUTH_INVALID_CREDENTIAL`              | 401    | Invalid API key or session token.                           |
| `AUTH_INVALID_FORMAT`                  | 401    | Invalid API key format.                                     |
| `AUTH_KEY_EXPIRY_IN_PAST`              | 422    | expiresAt must be in the future.                            |
| `AUTH_KEY_EXPIRY_TOO_FAR`              | 422    | Requested key expiry exceeds the maximum lifetime.          |
| `AUTH_KEY_NOT_FOUND`                   | 404    | API key not found.                                          |
| `AUTH_KEY_NO_ROLES`                    | 422    | At least one role is required.                              |
| `AUTH_ROLE_CEILING`                    | 403    | Cannot grant a role higher than your own.                   |
| `AUTH_SESSION_BAD_ALG`                 | 401    | The JWT declares an unexpected signing algorithm.           |
| `AUTH_SESSION_BAD_SIGNATURE`           | 401    | The JWT signature does not verify.                          |
| `AUTH_SESSION_EXPIRED`                 | 401    | The session token is past its expiry.                       |
| `AUTH_SESSION_INVALID`                 | 401    | The JWT payload fails validation.                           |
| `AUTH_SESSION_MALFORMED`               | 401    | The bearer token is not a parseable JWT.                    |
| `AUTH_SESSION_NOT_CONFIGURED`          | 422    | Wallet-session auth is not configured on the server.        |
| `AUTH_SESSION_REVOKED`                 | 401    | Session has been revoked. Sign in again.                    |
| `AUTH_SESSION_UNAVAILABLE`             | 401    | Session auth is not enabled on this server.                 |
| `AUTH_USER_ID_INVALID`                 | 422    | userId must be a valid identifier.                          |
| `AUTH_USER_INACTIVE`                   | 422    | Cannot create API keys for inactive users.                  |
| `AUTH_USER_NOT_FOUND`                  | 404    | User not found.                                             |

### Wallet auth: registration, login & recovery

SEP-10 challenge flows. Challenges are single-use and short-lived: always request a fresh one, sign it with the exact wallet, and submit it unmodified.

| Code                             | Status | Summary                                            |
| -------------------------------- | ------ | -------------------------------------------------- |
| `RECOVERY_BAD_SIGNATURE`         | 403    | Signature does not prove ownership of the address. |
| `RECOVERY_CHALLENGE_REUSED`      | 403    | This challenge has already been used.              |
| `RECOVERY_KEY_LIMIT_REACHED`     | 409    | This account is at its active API-key limit.       |
| `RECOVERY_WALLET_NOT_REGISTERED` | 404    | No registered account is linked to this wallet.    |
| `REGISTRATION_BAD_SIGNATURE`     | 403    | Signature does not prove ownership of the address. |
| `REGISTRATION_CHALLENGE_REUSED`  | 403    | This challenge has already been used.              |
| `REGISTRATION_CLOSED`            | 403    | Self-registration is disabled.                     |
| `REGISTRATION_EMAIL_TAKEN`       | 409    | A user with that email already exists.             |
| `REGISTRATION_WALLET_TAKEN`      | 409    | This wallet is already registered.                 |
| `SESSION_BAD_SIGNATURE`          | 403    | Signature does not prove ownership of the address. |
| `SESSION_CHALLENGE_REUSED`       | 403    | This challenge has already been used.              |
| `SESSION_USER_INACTIVE`          | 403    | This account is deactivated.                       |
| `SESSION_WALLET_NOT_REGISTERED`  | 404    | No registered account is linked to this wallet.    |
| `WALLET_BAD_SIGNATURE`           | 403    | Signature does not prove ownership of the address. |
| `WALLET_CANNOT_REMOVE_LAST`      | 409    | You cannot remove your last verified wallet.       |
| `WALLET_CHALLENGE_EXPIRED`       | 422    | The challenge has expired. Request a new one.      |
| `WALLET_LINK_NOT_FOUND`          | 404    | No wallet-link challenge found.                    |
| `WALLET_NOT_FOUND`               | 404    | No such wallet is linked to your account.          |
| `WALLET_OWNED_BY_OTHER`          | 422    | This address is already linked to another account. |

### Users, platforms & subjects

| Code                        | Status | Summary                                                        |
| --------------------------- | ------ | -------------------------------------------------------------- |
| `PLATFORM_ID_INVALID`       | 422    | platformId must be a numeric string.                           |
| `PLATFORM_NOT_FOUND`        | 404    | Platform not found for this account.                           |
| `PLATFORM_REQUIRED`         | 422    | This account has no active platform for this operation.        |
| `SUBJECT_EXTERNAL_ID_TAKEN` | 409    | Another subject of this platform already uses that externalId. |
| `SUBJECT_NOT_FOUND`         | 404    | Subject not found under this platform.                         |
| `USER_EMAIL_TAKEN`          | 409    | A user with that email already exists.                         |
| `USER_ID_INVALID`           | 422    | userId must be a valid identifier.                             |
| `USER_NOT_FOUND`            | 404    | User not found.                                                |
| `USER_NO_ROLES`             | 422    | At least one role is required.                                 |

### Request validation

| Code                                   | Status | Summary                                                    |
| -------------------------------------- | ------ | ---------------------------------------------------------- |
| `AMOUNT_INVALID`                       | 422    | amount is too large to be represented exactly.             |
| `AMOUNT_OUT_OF_RANGE`                  | 422    | amount is larger than the maximum on-chain value (i128).   |
| `AMOUNT_PRECISION_UNSUPPORTED`         | 422    | An amount has more decimal places than the asset supports. |
| `ESCROW_FILTER_FORBIDDEN`              | 403    | The credential cannot use the requested escrow filter.     |
| `ESCROW_MILESTONE_TARGET_OUT_OF_RANGE` | 422    | A milestone target does not fit in a u32.                  |
| `ESCROW_RECEIVER_MEMO_OUT_OF_RANGE`    | 422    | receiverMemo does not fit in a u32.                        |
| `INVALID_CURSOR`                       | 422    | Malformed pagination cursor.                               |
| `PLATFORM_FEE_TOO_HIGH`                | 422    | platformFee plus the Trustless Work fee would exceed 100%. |

### Trustlines & assets

| Code                               | Status | Summary                                                        |
| ---------------------------------- | ------ | -------------------------------------------------------------- |
| `STELLAR_TRUSTLINE_INVALID_FORMAT` | 422    | trustline could not be resolved to an asset contract.          |
| `STELLAR_TRUSTLINE_MISSING`        | 422    | Escrow state carries no readable trustline address.            |
| `STELLAR_TRUSTLINE_NOT_FOUND`      | 422    | No contract deployed at the trustline address on this network. |
| `STELLAR_TRUSTLINE_NOT_SEP41`      | 422    | The contract does not implement the SEP-41 token interface.    |
| `STELLAR_UNSUPPORTED_DECIMALS`     | 500    | The token reports decimals outside the supported range.        |
| `TRUSTLINE_DECIMALS_UNSUPPORTED`   | 422    | The asset decimals are outside the supported \[0, 18] range.   |

## Stellar network errors

### Transaction submission

Raised by `POST /stellar/send-transaction`: either the envelope is rejected before broadcast (not built by this API, wrong shape) or the network refuses it.

| Code                               | Status | Summary                                                      |
| ---------------------------------- | ------ | ------------------------------------------------------------ |
| `STELLAR_INVALID_SIGNED_XDR`       | 422    | signedXdr is not a valid transaction envelope.               |
| `STELLAR_TX_BAD_AUTH`              | 422    | The signature does not match the source account.             |
| `STELLAR_TX_BAD_AUTH_EXTRA`        | 422    | The transaction includes signatures that no operation needs. |
| `STELLAR_TX_BAD_SEQ`               | 409    | Stale sequence number; rebuild and resubmit.                 |
| `STELLAR_TX_CONTRACT_NOT_ALLOWED`  | 422    | Transaction invokes a contract this API does not manage.     |
| `STELLAR_TX_FEE_BUMP_INNER_FAILED` | 422    | The inner transaction of the fee bump failed.                |
| `STELLAR_TX_FEE_BUMP_REJECTED`     | 422    | Fee-bump transactions are not accepted.                      |
| `STELLAR_TX_HOST_FN_NOT_ALLOWED`   | 422    | Only invokeContract host functions may be submitted.         |
| `STELLAR_TX_INSUFFICIENT_BALANCE`  | 422    | The source account cannot cover the fee.                     |
| `STELLAR_TX_INSUFFICIENT_FEE`      | 422    | The fee is below what the network currently demands.         |
| `STELLAR_TX_INTERNAL_ERROR`        | 503    | The network reported a transient internal error.             |
| `STELLAR_TX_MISSING_OPERATION`     | 422    | The transaction does not contain any operations.             |
| `STELLAR_TX_NOT_SUPPORTED`         | 422    | Transaction type not supported on the current protocol.      |
| `STELLAR_TX_NO_OPS`                | 422    | Transaction carries no operations.                           |
| `STELLAR_TX_NO_SOURCE_ACCOUNT`     | 422    | The source account does not exist on the network.            |
| `STELLAR_TX_OPERATION_FAILED`      | 422    | One or more operations failed.                               |
| `STELLAR_TX_OP_NOT_ALLOWED`        | 422    | Only Soroban invokeHostFunction operations may be submitted. |
| `STELLAR_TX_TOO_EARLY`             | 422    | Submitted before the transaction validity window.            |
| `STELLAR_TX_TOO_LATE`              | 422    | The transaction validity window has passed.                  |
| `STELLAR_TX_UNPARSEABLE`           | 422    | signedXdr is not a valid transaction envelope.               |

### Stellar infrastructure & state

RPC/Horizon connectivity, simulation plumbing, and archived contract state. Mostly retryable; report persistent ones with the `traceId`.

| Code                              | Status | Summary                                                             |
| --------------------------------- | ------ | ------------------------------------------------------------------- |
| `STELLAR_FACTORY_RETURN_SHAPE`    | 500    | The factory returned an unexpected value shape.                     |
| `STELLAR_HORIZON_UNMAPPED`        | 500    | Horizon answered with an unrecognized error shape.                  |
| `STELLAR_HORIZON_UNREACHABLE`     | 500    | Could not communicate with Horizon.                                 |
| `STELLAR_RESTORE_UNBUILDABLE`     | 500    | A state-restore transaction could not be built.                     |
| `STELLAR_RETURN_VALUE_SHAPE`      | 500    | A contract returned data in an unexpected shape.                    |
| `STELLAR_RPC_TIMEOUT`             | 500    | The Soroban RPC did not answer within the deadline.                 |
| `STELLAR_RPC_UNAVAILABLE`         | 500    | The Soroban RPC is unreachable.                                     |
| `STELLAR_SIMULATION_FAILED`       | 500    | Contract simulation failed.                                         |
| `STELLAR_SIMULATION_MISSING`      | 500    | The RPC returned no simulation result.                              |
| `STELLAR_STATE_ARCHIVED`          | 409    | Contract state is archived; sign the provided restoreXdr and retry. |
| `STELLAR_TX_FAILED`               | 500    | The network rejected the transaction.                               |
| `STELLAR_UNKNOWN_CONTRACT_METHOD` | 500    | The target contract does not expose the invoked method.             |

## Transport-level errors

Generic codes produced by the HTTP layer when no domain-specific code applies.

| Code                  | Status | Summary                                        |
| --------------------- | ------ | ---------------------------------------------- |
| `BAD_REQUEST`         | 400    | The request failed basic validation.           |
| `CONFLICT`            | 409    | The request conflicts with current state.      |
| `FORBIDDEN`           | 403    | The credential lacks permission.               |
| `HTTP_ERROR`          | 500    | A non-standard HTTP error status was produced. |
| `INTERNAL_ERROR`      | 500    | An unexpected server error occurred.           |
| `NOT_FOUND`           | 404    | No route or resource matches the URL.          |
| `SERVICE_UNAVAILABLE` | 503    | A dependency is temporarily unavailable.       |
| `TOO_MANY_REQUESTS`   | 429    | You exceeded the rate limit.                   |
| `UNAUTHORIZED`        | 401    | Authentication is required or failed.          |
| `VALIDATION_ERROR`    | 422    | The request body failed validation.            |


---

# 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://docs.trustlesswork.com/trustless-work/v2-en/api-rest/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.