> For the complete documentation index, see [llms.txt](https://stonkfun.gitbook.io/stonkfun-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stonkfun.gitbook.io/stonkfun-docs/developer-api/errors.md).

# Errors

Every failure returns:

```json
{
  "error": {
    "code": "conflict",
    "message": "...",
    "retryable": false,
    "retryAfterSeconds": 30
  }
}
```

Branch on `code`, which is stable. Messages are written for humans and may be reworded.

## Codes

| Code                  | HTTP | Meaning                                                                                                                                                                                 |
| --------------------- | ---: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`     |  400 | A parameter is missing or malformed.                                                                                                                                                    |
| `forbidden`           |  403 | Refused outright, and repeating it will not help. A reward launch while those are admin-only, or a fee claim by a wallet that does not hold the Fee Key. No credential would change it. |
| `not_found`           |  404 | No such resource.                                                                                                                                                                       |
| `method_not_allowed`  |  405 | Wrong HTTP method for this path.                                                                                                                                                        |
| `conflict`            |  409 | Well-formed, but the moment is wrong. See below.                                                                                                                                        |
| `rate_limited`        |  429 | Per-minute limit exceeded. Honour `Retry-After`.                                                                                                                                        |
| `internal`            |  500 | Something broke on our side. Safe to retry.                                                                                                                                             |
| `service_unavailable` |  503 | A dependency or feature is temporarily unavailable.                                                                                                                                     |

## `409` means two different things

The right response depends on which endpoint returned it.

**On a launch**, the payment landed and the launch needs manual recovery. Never retry and never re-pay, since a second payment creates a second token. See [If a launch gets stuck](/stonkfun-docs/launching/recovery.md).

**On a fee claim**, either nothing is claimable yet or the prepared claim expired, since they last 90 seconds. Preparing again is the fix, and it costs nothing.

## `503` on submit

If a launch bundle does not land, `/launches/submit` answers `service_unavailable` with:

```json
{ "charged": false }
```

Nothing was charged and no token exists. The retry is a fresh quote from `/prepare` rather than a resubmission, because the old quote's payment blockhash expires on its own.

## `503` from an unavailable feature

A `503` also appears when an optional feature is currently switched off:

| Situation                | Endpoint                                                |
| ------------------------ | ------------------------------------------------------- |
| Dev buys unavailable     | `/launches/prepare` with `devBuyPercent` or `devBuySol` |
| Airdrop mode unavailable | `/launches/prepare` with any airdrop parameter          |
| API launching paused     | `/launches/prepare`, `/launches/submit`                 |
| API claiming paused      | `/tokens/{mint}/fees/claim/*`                           |

## `403` on `mode: 'reward'`

While reward launches are restricted to admins, `mode: 'reward'` requires an admin password header. Without it, `/prepare` answers `403`.

## `404` on `/tokens/{mint}/airdrop`

This route exists only where airdrops do. With the feature off, it `404`s and is omitted from the OpenAPI spec entirely.

A token that simply launched without an airdrop answers `200` with `airdrop: null`, which is not an error. Most tokens have no airdrop.

## Retry guidance

| Code                                      | Retry?                             |
| ----------------------------------------- | ---------------------------------- |
| `invalid_request`                         | No. Fix the request.               |
| `forbidden`                               | No. No credential would change it. |
| `not_found`                               | No                                 |
| `method_not_allowed`                      | No                                 |
| `conflict` on a claim                     | Yes, prepare again                 |
| `conflict` on a launch                    | **No, and never re-pay**           |
| `rate_limited`                            | Yes, after `Retry-After`           |
| `internal`                                | Yes                                |
| `service_unavailable` on submit           | Yes, with a fresh quote            |
| `service_unavailable` from a feature gate | No. The feature is off.            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://stonkfun.gitbook.io/stonkfun-docs/developer-api/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.