> For the complete documentation index, see [llms.txt](https://docs.peach.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peach.ag/api-reference/arc-aggregator/error-codes.md).

# Error Codes

Shared error meanings and handling for Arc HTTP APIs. Distinguishes HTTP status codes from JSON application codes.

### Read HTTP status and JSON code separately

This reference applies to the Arc endpoints under `https://api.peach.ag/arc`. Business failures normally return **HTTP 200** with a non-200 JSON `code`. Only `code: 200` represents API success; transaction construction does not mean that a swap has executed on-chain. Error envelopes omit `data`.

Request parsing, payload limits and service middleware can instead return non-2xx HTTP statuses. Those responses may be plain text rather than the JSON envelope. Do not convert an HTTP status into an application code.

```
{
  "code": 4000,
  "msg": "version too low"
}
```

The example above is an application failure returned with HTTP 200. `msg` gives the specific reason; clients should branch on the code and use the message for diagnosis.

### Application codes

The following codes are carried in the JSON response body. Their HTTP status is normally 200.

| JSON code | Meaning                                | Typical cause and handling                                                                                                                                                                                                                                                                                 |
| --------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`     | Success                                | Use the endpoint's data. For swap/build, validate and simulate the constructed transaction before submitting it.                                                                                                                                                                                           |
| `400`     | Unclassified application failure       | Fallback for an error without a specific application-code mapping, including some validation or construction failures. Find Routes and Direct Swap may expose the underlying reason; Prepare and Build may return “Unknown error”. Inspect msg; do not assume this is HTTP 400 or blindly retry.           |
| `4000`    | Invalid request or invalid quote state | Examples: zero amount, identical tokens, missing executor, incompatible payer/executor roles, unsupported native flags, execution-step limit, expired quote or exhausted build attempts. Correct the request. For an expired or exhausted delegated quote, prepare again and obtain a new payer signature. |
| `4040`    | Token risk rejected                    | The output token is flagged as a honeypot that can prevent selling after purchase. Stop the request and surface the risk; retrying unchanged does not resolve it. This is unrelated to HTTP 404.                                                                                                           |
| `5000`    | Internal processing failure            | Quote calculation, deviation checks or stored execution data failed an internal check. Read msg. Retry only if the condition appears temporary; report recurring failures with a trace ID when available.                                                                                                  |
| `5010`    | No usable route                        | No route graph, insufficient usable liquidity, all routes capped, or the full input amount cannot be routed. Recheck the pair, amount and provider constraints. Re-quote after conditions change; never submit an incomplete route.                                                                        |
| `5030`    | Execution service unavailable          | The transaction builder is disabled, required execution configuration/signing is unavailable, or configuration changed during construction. Retry with backoff only for temporary failures; persistent configuration failures require service support.                                                     |

#### Defined compatibility codes

| JSON code | Meaning                 | Current behavior                                                                                                                                                                                                                                                 |
| --------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `4030`    | Forbidden               | Defined in the shared application-code mapping; the documented Arc endpoint handlers do not currently emit it directly. If returned, stop and check the rejection reason and integration access.                                                                 |
| `5040`    | Unsupported API version | Defined in the shared mapping, but the current Find Routes version check returns `4000` with `msg: "version too low"`. Send `v=1001500`; an omitted version is treated as 0. Do not rely on 5040 as the only version error, and do not confuse it with HTTP 504. |

### HTTP errors and service middleware

| HTTP status | Body / JSON code                               | Meaning and handling                                                                                                                                                                    |
| ----------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | Usually plain-text parsing error               | Malformed or incomplete query parameters, invalid JSON syntax, or an unreadable request body. Correct the request before retrying.                                                      |
| `413`       | Usually plain text                             | Request body too large. The Build endpoint accepts at most **4 KiB**; send only quote\_id and payer\_signature.                                                                         |
| `415`       | Usually plain text                             | JSON request has a missing or unsupported Content-Type. Set `Content-Type: application/json`.                                                                                           |
| `422`       | Usually plain text                             | JSON is syntactically valid but cannot be decoded into the required request fields/types. Check required fields and their formats.                                                      |
| `429`       | May be JSON or plain text                      | Too many requests. Reduce request rate and concurrency, then retry with backoff. Honor Retry-After when present.                                                                        |
| `500`       | `code: 500`, `msg: "Internal Server Error"`    | The service's panic handler returns this envelope. Treat it as a server failure; use bounded backoff and report recurring errors. Other infrastructure may return a different 500 body. |
| `503`       | `code: 503`, `msg: "Service Circuit Breaking"` | The service-wide limiter rejected the request. Reduce concurrency and request rate, then retry with backoff. This is different from business code `5030`.                               |

Gateways may return additional HTTP errors with a different body. Treat unknown non-2xx responses as HTTP failures and parse the JSON envelope only when present. Handle both HTTP 429 and HTTP 503 rate-limit responses. The documented rate is 300 requests/minute, equivalent to an average of 5 requests/second.

### Endpoint-specific handling

* **Get Status:** the normal handler returns code 200. It can still encounter shared HTTP/service failures.
* **Find Routes:** version validation uses 4000; liquidity failures use 5010; a rejected target token uses 4040.
* **Build Swap Calldata:** payer must equal executor. If they differ, use the delegated Prepare flow. Some construction failures use fallback code 400.
* **Prepare Delegated Swap:** payer must differ from executor and recipient is required. Invalid roles use 4000; execution service configuration failures use 5030.
* **Build Delegated Swap:** expired/missing quotes and build-attempt exhaustion use 4000. Build does not re-quote. Start a new Prepare flow and sign its new authorization when the old quote is no longer usable. Invalid signature hex or length also uses 4000; use the signature for the same quote.

### Retry and diagnostics

For temporary service failures, use bounded exponential backoff with jitter and honor Retry-After when present. Do not retry validation, token-risk or expired-quote errors unchanged. Build retries count toward the per-quote attempt limit and cannot extend the deadline.

For support, retain the endpoint, HTTP status, JSON code, msg and x-trace-id when available. Redact API keys and never log payer signatures. Unknown application codes must be treated as failures; never consume data or construct a transaction from an error response.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peach.ag/api-reference/arc-aggregator/error-codes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
