> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eluup.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Errors & Troubleshooting

> HTTP errors, validation failures, payment failures, and troubleshooting guidance for ELUUP x402 APIs.

Use this page when an ELUUP x402 request does not return the expected successful response. It covers request validation, token resolution, backend failures, payment failures, status codes, and nullable response fields.

## Request Validation

Before any payment is requested, every batch endpoint validates the request body in this order. A request failing any step below is rejected with `400` and **no payment is charged**.

### Schema validation

The request body must match the endpoint's schema (correct field names, types, required fields). Validation errors are returned as:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "tokens: Too small: expected array to have >=1 items"
}
```

The `error` string is built as `"<field path>: <message>"`, joined with `; ` if multiple fields fail. Common cases:

| Condition              | Example error                                         |
| ---------------------- | ----------------------------------------------------- |
| Empty `tokens` array   | `tokens: Too small: expected array to have >=1 items` |
| Missing required field | `tokens.0.identifier: Required`                       |
| Wrong type             | `tokens.0.limit: Expected number, received string`    |

### Batch size limit

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Maximum 5 tokens are allowed per request. Received 6."
}
```

### Duplicate token rejection

If the same token identifier (case-insensitive) appears more than once in `tokens`, the entire request is rejected — you are **not** charged for the duplicate:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Duplicate tokens are not allowed in a single batch request."
}
```

```json theme={null}
// Rejected — same identifier, different casing
{ "tokens": [{ "identifier": "mcade" }, { "identifier": "MCADE" }] }
```

### Token resolution

After passing the checks above, every identifier in the batch is resolved against on-chain/market data. **Resolution fails closed on the whole batch** — if even one identifier can't be resolved, the entire request is rejected with `404` and, again, no payment is charged:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Token not found for identifier: notarealtoken"
}
```

This means a batch is always all-or-nothing: either every token resolves and you pay for exactly that many, or nothing resolves and nothing is charged. Payment is only requested once every token in the batch has been confirmed to resolve.

***

## Error Handling Overview

Errors fall into four categories:

1. **Request validation errors** — `400` ([Request Validation](#request-validation))
2. **Duplicate-token errors** — `400` ([Duplicate token rejection](#duplicate-token-rejection))
3. **Token resolution errors** — `404` ([Token resolution](#token-resolution))
4. **x402 payment errors** — `402`, generated by the payment middleware, **not** the application wrapper ([HTTP 402 — Payment Required](/x402/payment-flow#http-402-payment-required))

Plus endpoint-specific backend failures (`502` on `/v1/token-prices`, `404` on `/v1/top-performers` and `/v1/aggregate-metrics` if their underlying logic fails).

***

## HTTP 400 — Validation Error

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "<field path>: <validation message>"
}
```

The `error` string is derived from schema validation and will reference the offending field path (e.g. `tokens`, `tokens.0.identifier`).

***

## HTTP 400 — Batch Limit Error

Requests with more than 5 tokens are rejected before any payment is requested:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Maximum 5 tokens are allowed per request. Received 8."
}
```

***

## HTTP 400 — Duplicate Token Error

Requests containing the same token identifier more than once (case-insensitive) are rejected before any payment is requested:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Duplicate tokens are not allowed in a single batch request."
}
```

***

## HTTP 404 — Token Resolution Error

If any identifier in the batch can't be resolved, the entire batch is rejected — no payment is requested:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Token not found for identifier: notarealtoken"
}
```

`/v1/top-performers` and `/v1/aggregate-metrics` also return `404` (with the same wrapper) if their underlying logic returns an unsuccessful result — in that case payment has already been made, since these are non-batch endpoints without a pre-payment resolution step.

***

## HTTP 502 — Backend Error

`/v1/token-prices` returns `502` if its underlying price logic fails, using the standard response wrapper.

***

## Status Code Summary

| HTTP Status | Meaning                                                                                                               |
| ----------: | --------------------------------------------------------------------------------------------------------------------- |
|       `200` | Request successfully processed                                                                                        |
|       `400` | Schema validation failed, batch exceeds 5 tokens, or duplicate tokens in batch                                        |
|       `402` | x402 payment required or rejected — see [HTTP 402 — Payment Required](/x402/payment-flow#http-402-payment-required)   |
|       `404` | Token resolution failed, or endpoint logic returned an unsuccessful result                                            |
|       `502` | `/v1/token-prices` backend/logic failure                                                                              |
|       `500` | Not explicitly generated by the documented route handlers; may originate from general upstream/Express error handling |

***

## Nullable Fields

| Endpoint                       | Field(s)                                     | `null` when                  |
| ------------------------------ | -------------------------------------------- | ---------------------------- |
| Token Signals / Signal History | `previousShortSMA`, `previousLongSMA`        | Insufficient historical data |
| Token Win Rate                 | `winRate`                                    | Insufficient data            |
| Token Average Prices           | `averageBuyPriceETH`, `averageBuyPriceUSD`   | No valid buy data exists     |
| Token Average Prices           | `averageSellPriceETH`, `averageSellPriceUSD` | No valid sell data exists    |

Consumers must not assume these fields are always numeric.

***

**x402 docs:** [Overview](/x402) · [Quickstart](/x402/quickstart) · [Payment Flow](/x402/payment-flow) · [API Reference](/x402/api-reference) · [Errors & Troubleshooting](/x402/errors) · [Examples](/x402/examples)