# Errors

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

> **TIP: 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 {#every-code-v1-can-return}

This table is generated from the API's 22-code v1 catalog. Mint handlers and middleware can return additional codes; see [SDK error handling](https://docs.deads.io/sdk/gravemint.md#errors-and-retries) 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 {#the-mint-time-ones-worth-reading-twice}

- `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](https://docs.deads.io/guides/signing.md).
- `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.

---
Source: https://docs.deads.io/guides/errors
Markdown: https://docs.deads.io/guides/errors.md