Errors

The Error Format

A failed request returns a JSON body with one error object:

{ "error": { "message": "Invalid API key" } }

These are real responses, captured on 12 October 2026 from requests sent without a valid key:

curl -i https://api.mallow.art/v1/artworks/trending
# HTTP/2 401
# {"error":{"message":"Invalid API key"}}

curl -i https://api.mallow.art/v2/auctions/So11111111111111111111111111111111111111112
# HTTP/2 401
# {"error":{"message":"Unauthorized"}}

Some /v1 errors add fields:

• A validation error adds error.details, the full list of problems. See VALIDATION_ERROR
• Some errors add an info object beside error, with the values the request was about

Responses Without the Format

A few failures are returned before the request reaches mallow's handlers, and their body isn't JSON. Read the body as text before you parse it.

HTTP Statuses

The reference pages list 400, 401, 404, 409, 429 and 500. The API also returns the other statuses in this table.

404

The other /v2 builders return a 400 for a missing listing, auction, offer or raffle, not a 404.

409

Only Buy on Magic Eden returns 409. The order's price, currency, expiry or escrow changed after the quote, or the total passed the limits you sent. The message starts with STALE_ORDER:. Request the quote again and show the buyer the new terms.

Error Codes

These are all the codes the public API sets. All four come from /v1.

Every other error has no code, including every 401.

A validation error has this shape. The values are placeholders:

{
  "error": {
    "message": "<field>: <problem>",
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "location": "body",
        "issues": [{ "path": "<field>", "message": "<problem>" }]
      }
    ]
  }
}

Failures Inside a 200

Two groups of operations report a failure in a successful response. Check the body, not only the status.

• Draw submit and draw status. Send signed gumball draws, Gumball draw status and the Jellybean versions return one result per transaction. A refused or failed draw has an error with a message. See Draws go through mallow
• Magic Eden quote. Magic Eden buy quote returns available: false with a reason when the order can't be bought

A state read that finds nothing is also a 200, with null in place of the state. Treat that as a valid answer.

What Is Safe to Retry

Retry 408, 429, 500 and 503. Don't retry any other 4xx without changing the request. The quickstart has a retry helper.

On-Chain Failures

The API builds transactions and you run them. A transaction can build without error and still fail when you send it, and that failure comes back from your Solana RPC rather than from mallow.

It shows up in one of two places:

• At send time. The RPC simulates the transaction first and rejects it, with the program logs in the error
• After it lands. The signature's status carries an err, which confirmTransaction returns in value.err

Either way the error names the instruction that failed and a number:

{ "InstructionError": [2, { "Custom": 6002 }] }

Here 2 is the position of the instruction in the transaction, and 6002 is the error code of the program that instruction calls. The same number means different things in different programs, so find the program first. Its address is in the decoded transaction and in the logs. SDKs and programs lists mallow's.

mallow's programs number their own errors from 6000. Where to look a code up:

Common causes are a listing that sold or was cancelled between the build and the send, a wallet without enough funds for the price and fees, and an expired blockhash. For the last one, see Blockhash expiry.

Draws are the exception, because mallow sends them. A draw that fails simulation comes back from the submit call with an error and its logs. A draw that fails on chain shows up in the status call.