Errors

API errors provide a message and, where available, a machine-readable code. Use the code for application logic and the message for context.

Handling error responses

The sentence is written for a person and may be reworded at any time. The code is part of the contract and will not change within v1.

AUTH_UNAVAILABLE and LOOKUP_FAILED indicate a temporary lookup failure. Retry with backoff; these responses do not establish that a key or collection is invalid.

v1 error catalog

This table is generated from the API's 22-code v1 catalog. Mint handlers and middleware can return additional codes; see SDK error handling and retain a message fallback for unfamiliar responses.

code	status	retry	meaning and what to do
API_KEY_EXPIRED	401	no	The key is past its expiry. Request a new one.
API_KEY_INACTIVE	401	no	The key exists but is disabled. Request a replacement or ask for its status to be reviewed.
API_KEY_INVALID	401	no	The key did not match a live record. Check the key. Terminal — do not retry.
API_KEY_REQUIRED	401	no	No key, and no recognised origin. Send X-API-Key, or ask us to register your origin.
AUTH_UNAVAILABLE	503	yes	The authentication check could not complete. Retry with backoff; the key has not been rejected.
CHAIN_DISABLED	400	no	That chain is retired or paused. Terminal. Fall back to capabilities.mintUrl.
CHAIN_NOT_SUPPORTED_BY_SURFACE	400	no	v1 mints Solana only. Use the mint page for other chains.
CLIENT_BROADCAST_NOT_ALLOWED	400	no	You sent a transaction hash — meaning you broadcast it yourself. Send signedTransaction as base64. GraveMint submits the transaction.
CODE_REQUIRED	400	no	A claim-code check arrived with no code. Send { code } in the body.
COLLECTION_CLOSED	409	no	The drop is closed. Terminal for minting; the read still works.
COLLECTION_NOT_FOUND	404	no	No live drop matches that identifier. Check the short ID, UUID or on-chain address and the key scope.
COLLECTION_NOT_IN_SCOPE	403	no	The key was not issued for that drop. A key is scoped to specific collections. Terminal.
COLLECTION_REQUIRED	400	no	No collection was supplied. Include collectionId.
LOOKUP_FAILED	503	yes	We could not load the drop. Retry shortly. Not a statement about whether it exists.
NFTS_LOCKED	409	yes	The items are briefly held by another mint that is still settling. Supply is temporarily reserved. Ask the collector to try again shortly.
NOT_ELIGIBLE	403	no	This wallet does not meet the phase requirements. Show the reason from the eligibility endpoint. Terminal for this wallet/phase.
ORIGIN_NOT_ALLOWED	403	no	This origin is not on the key. Request registration of the exact origin, including staging and previews.
RATE_LIMITED	429	yes	Too many requests. Back off and honour Retry-After.
SESSION_EXPIRED	410	no	The prepared session timed out before the signature came back. Call prepare again. Never reuse a stale session.
TX_MODIFIED	400	no	The signed transaction does not match what we built. Check the signing adapter, then prepare a new transaction. Do not resend modified bytes.
UNSUPPORTED_BY_SURFACE	409	no	The collection requires features outside the core mint flow. Read capabilities.requiresFeatures and offer capabilities.mintUrl when available.
WALLET_MISMATCH	400	no	The signing wallet is not the wallet the session was prepared for. Prepare and sign with the same wallet.

Mint recovery

• NFTS_LOCKED: supply is temporarily reserved by another mint. Try again shortly.
• TX_MODIFIED: correct the signing adapter before preparing a new transaction.
• CLIENT_BROADCAST_NOT_ALLOWED: send signed bytes for server submission. See signing.
• OUTCOME_UNKNOWN: the SDK cannot confirm the submitted mint's outcome. Retain session IDs and check the wallet before starting another mint. This SDK error is separate from the API catalog above.

For batches, inspect each returned transaction's errorCode and pending fields, even when the HTTP request succeeds.