Errors

Errors are JSON with a detail field. Only a 2xx response settles an x402 payment, so every error on this page is free.

Status	Meaning	Settled	What to do
`400`	The request is valid JSON but cannot be served: unknown market, bad constraint, unsupported chain or token, or `InsufficientCapacity`	No	Read `detail`, fix the request
`401`	Partner headers are present but wrong, or missing while x402 is off	No	Check both headers. A wrong key never falls back to payment
`402`	Payment needed, invalid, for the wrong amount, or settlement failed	No	Sign the offer in `PAYMENT-REQUIRED` and retry
`422`	The body does not match the schema, or `current_allocations` sums above `total_capital`	No	Read the field errors in `detail`
`500`	Unexpected server error	No	Retry with backoff
`503`	A feature is not enabled, for example monitor sessions	No	Use partner headers or try later

400

Constraint mistakes name the expected parameters:

{
  "detail": "Invalid max_amount_per_protocol constraint: 'max_ratio' must be greater than 0 and at most 1. Expected params: protocol (market name), max_ratio (fraction of total_capital, greater than 0 and at most 1; 0.4 means 40%)"
}

Insufficient capacity

Internally this is InsufficientCapacity. The risk rules and your constraints leave less room than total_capital. The detail says how much fits:

{
  "detail": "Optimization failed: The liquidity and health rules allow 3120000000000 of 5000000000000 to be placed across the requested protocols. Lower total_capital or add protocols."
}

Here 5,000,000 USDC (5000000000000) was requested and 3,120,000 USDC (3120000000000) fits. Lower total_capital, add markets from the market list, or relax a constraint. The service never returns a partial plan.

401

{ "detail": "Invalid or missing partner API key" }

402

The body and the base64 PAYMENT-REQUIRED header carry the same offer. error explains why:

`error`	Cause
`PAYMENT-SIGNATURE header is required`	First call, no payment yet
`PAYMENT-SIGNATURE is not a valid base64 x402 payload`	The header could not be decoded
`Only x402 version 2 payments are accepted`	A version 1 payload was sent
`Payment does not match the current price or terms for this call`	Wrong amount, asset, network, or recipient. The price may have changed
`Payment settlement failed: ...`	Verified, ran, but did not settle. Sign a new payload

See Authentication and payments for the full offer.

422

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "Value error, current_allocations sum to 1200000000, which exceeds total_capital 1000000000"
    }
  ]
}

Over MCP

A failed tool call returns isError: true with the same body in structuredContent: the offer for a payment problem, or {"status": 400, "detail": "..."} for anything else. See API MCP.

Get started

API

Agents

Reference

400

Insufficient capacity

401

402

422

Over MCP