x402 Errors & Troubleshooting

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:

{
  "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

{
  "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:

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

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

{
  "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:

Request validation errors — 400 (Request Validation)
Duplicate-token errors — 400 (Duplicate token rejection)
Token resolution errors — 404 (Token resolution)
x402 payment errors — 402, generated by the payment middleware, not the application wrapper (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

{
  "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:

{
  "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:

{
  "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:

{
  "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
`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 · Quickstart · Payment Flow · API Reference · Errors & Troubleshooting · Examples

Get Started

Core Concepts

Agents

CLI

MCP Server

x402 Payments

Reference

x402 Errors & Troubleshooting

Request Validation

Schema validation

Batch size limit

Duplicate token rejection

Token resolution

Error Handling Overview

HTTP 400 — Validation Error

HTTP 400 — Batch Limit Error

HTTP 400 — Duplicate Token Error

HTTP 404 — Token Resolution Error

HTTP 502 — Backend Error

Status Code Summary

Nullable Fields

​Request Validation

​Schema validation

​Batch size limit

​Duplicate token rejection

​Token resolution

​Error Handling Overview

​HTTP 400 — Validation Error

​HTTP 400 — Batch Limit Error

​HTTP 400 — Duplicate Token Error

​HTTP 404 — Token Resolution Error

​HTTP 502 — Backend Error

​Status Code Summary

​Nullable Fields

Request Validation

Schema validation

Batch size limit

Duplicate token rejection

Token resolution

Error Handling Overview

HTTP 400 — Validation Error

HTTP 400 — Batch Limit Error

HTTP 400 — Duplicate Token Error

HTTP 404 — Token Resolution Error

HTTP 502 — Backend Error

Status Code Summary

Nullable Fields