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

# Errors, retries and idempotency

Trading integrations must distinguish a request failure from an unknown submission result and from a committed business rejection.

Blind retries can create duplicate intent, nonce conflicts or confusing client state.

## REST error categories

The public API uses stable error categories such as:

| Code                   | Meaning                                            |
| ---------------------- | -------------------------------------------------- |
| `MALFORMED_REQUEST`    | Request cannot be parsed or decoded                |
| `VALIDATION_ERROR`     | Request or transaction fields are invalid          |
| `UNAUTHORIZED`         | Authentication/authorization failed                |
| `SESSION_REQUIRED`     | A valid wallet session is required                 |
| `NOT_FOUND`            | Requested resource is not known                    |
| `RATE_LIMITED`         | Client exceeded a rate or admission limit          |
| `IDEMPOTENCY_CONFLICT` | The same idempotency key was reused inconsistently |
| `CURSOR_INVALIDATED`   | A pagination cursor can no longer be used          |
| `SERVICE_UNAVAILABLE`  | A required service is temporarily unavailable      |
| `INTERNAL_ERROR`       | Unexpected server-side failure                     |

The exact HTTP status and response schema are defined by the versioned OpenAPI contract.

## Transaction submission states

For `POST /api/v1/transactions`, distinguish these situations:

### Request rejected before submission

Examples include malformed JSON, an invalid signed payload or an idempotency conflict.

Fix the request before retrying.

### Accepted for submission

A `202` response means the transaction entered the submission flow. Continue with confirmation; do not create a second logical action.

### Submission outcome unknown

A client timeout or temporary dependency failure can leave the client unsure whether the signed transaction was accepted.

Use the transaction ID and confirmation endpoint to resolve the outcome before deciding what to do next.

### Committed business rejection

A transaction can be committed but produce a trading rejection such as insufficient margin or an invalid order condition.

That is a final trading outcome, not a reason to retry the same signed transaction indefinitely.

## Idempotency keys

Transaction submission requires an `Idempotency-Key`.

Recommended rules:

* generate one stable key per logical submission attempt;
* reuse it when retrying the **same signed transaction** after a transport failure;
* do not reuse it for a different signed payload;
* retain the key until the final outcome is known.

## Retry matrix

| Situation                                  | Recommended action                                                                  |
| ------------------------------------------ | ----------------------------------------------------------------------------------- |
| HTTP connection failed before any response | Retry the same signed request with the same idempotency key, then confirm by tx ID  |
| `202 Accepted`                             | Do not resubmit; poll confirmation or watch account transactions                    |
| `409 IDEMPOTENCY_CONFLICT`                 | Stop and reconcile the client request/key mapping                                   |
| `422` transaction rejection                | Treat as rejected; inspect the returned reason                                      |
| `429 RATE_LIMITED`                         | Back off and retry according to policy                                              |
| `503 SERVICE_UNAVAILABLE`                  | Back off; if submission may have happened, resolve by tx ID first                   |
| committed business rejection               | Update local trading state; build a new action only if the strategy still wants one |

## Nonce rule

Do not allocate a new nonce merely because an earlier HTTP request timed out.

First determine whether the earlier signed transaction is known or committed. Creating a new action without reconciliation can leave the client with gaps or conflicting intent.

## WebSocket errors

WebSocket clients should handle protocol errors such as invalid messages, missing/expired authentication, rate limits, invalid channels and unavailable resume state.

When resume is unavailable, recover with a fresh subscription/snapshot instead of continuing from an uncertain local sequence.


---

# 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://exliquid.gitbook.io/docs/developers/errors-retries-idempotency.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.