API
Errors
Every error code the Kodama API answers: its HTTP status, its message, what raises it and on which routes.
How an error arrives
A failed request answers the error envelope with the HTTP status of its code. Branch on error.code; show error.message; retry only when error.retryable is true, after error.retryAfterSeconds when it is there. The typed client throws the envelope as ApiClientError.
{
"error": {
"code": "CHAIN_REFUSED",
"message": "Exceeds desired slippage limit",
"retryable": false,
"stage": "simulation",
"programError": {
"programId": "LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj",
"name": "ExceededSlippage",
"number": 6004
}
}
}The contract defines 29 codes in backend/src/contract/errors.ts and backend/src/contract/schemas.ts. The client exports them with their statuses as errors.status.
In the tables, "the build routes" are the eight POST /v1/…/build routes, and "every route" includes the stream.
Every code
The first fifteen can answer any kind of request. The fourteen from CURVE_COMPLETE on belong to a plant, a trade or a tree action.
| Code | HTTP | Message | Raised when | Routes |
|---|---|---|---|---|
VALIDATION_ERROR | 400 | Check the highlighted fields. with fieldErrors, or a sentence naming the fault | A body, a query or a path value does not match the route's schema; the JSON does not parse; a metadata part is missing; a signed copy was changed by the wallet; a build was submitted in a mode or an order it does not allow; preparedMint names a tree already planted. Its messages are listed below. | Every route |
UNAUTHORIZED | 401 | Sign in to continue. | No route returns it: the API has no sign-in. | None |
ORIGIN_NOT_ALLOWED | 403 | This origin is not allowed. | The request's Origin header is not in the service's allowed origins. | Every route |
NOT_FOUND | 404 | By route, listed below | The path is no route; the mint was not launched here, or was planted moments ago and is not indexed yet (retryable: true, retryAfterSeconds: 3); the mint has no tree; the build id is unknown; the media file does not exist. | Every route |
PROGRAM_UNAVAILABLE | 409 | The platform is not live yet. The grove has not been set up yet. The platform lookup table is still settling. Try again in a moment. | The service is waiting for the program, the grove or the lookup table to exist on chain. retryable: true; the lookup table message carries retryAfterSeconds: 5. | GET /v1/platform, the build routes, POST /v1/transactions/submit |
CONFIGURATION_REQUIRED | 409 | A message naming what the upload is waiting on. | Metadata storage cannot take the upload at this moment. Retry later. | POST /v1/metadata |
IDEMPOTENCY_CONFLICT | 409 | This transaction was already submitted. | The build was submitted before under another idempotencyKey. | POST /v1/transactions/submit |
TRANSACTION_EXPIRED | 409 | This launch was held too long before it came back signed. Build it again. The prepared mint key is not available on this server. | A plant came back signed after the server let go of its mint key (retryable: true); or preparedMint names a mint whose key this server does not hold. A transaction that expires on chain is not this code: it is the status expired of following. | POST /v1/transactions/submit, POST /v1/launch/build |
PAYLOAD_TOO_LARGE | 413 | The request body is too large. | The body is over 8,388,608 bytes. | Every POST route |
UNSUPPORTED_MEDIA_TYPE | 415 | Send an application/json body. Send multipart/form-data with an image file and an info field. | The Content-Type is not the one the route takes. | Every POST route |
SIMULATION_FAILED | 422 | The chain refused this transaction., or the fault's own sentence | A transaction failed in simulation with no program error to name; or it could not be built: it does not fit a wallet transaction, or the chain read it needs came back incomplete. | The build routes, POST /v1/transactions/submit |
CHAIN_REFUSED | 422 | The program's own message, for example Exceeds desired slippage limit or Not enough tokens in the account. | A program refused the transaction in simulation, when it was built or when it was submitted. programError holds the program's address, the error's name and its number. | The build routes, POST /v1/transactions/submit |
RATE_LIMITED | 429 | Too many requests. Try again in a minute. | A client sent more than 60 POST requests in a minute (retryAfterSeconds is the rest of the minute). retryable: true. | Every POST route under /v1 |
INTERNAL_ERROR | 500 | The request could not be completed. | Anything the service did not expect. retryable: true, with requestId to quote. | Every route |
UPSTREAM_UNAVAILABLE | 502 | The Solana RPC did not answer. Try again in a moment. | The service's RPC failed during a chain read. retryable: true. The typed client also throws this code for a 5xx answer that is not the envelope. | GET /v1/platform, the build routes, submit, GET /v1/transactions/:id |
CURVE_COMPLETE | 409 | This coin sold out its curve and is moving to its Raydium pool. Trading resumes there in a moment. This coin just graduated; its Raydium pool is being indexed. Try again in a moment. This coin just graduated; its Raydium pool opens for trading in a moment. The graduated pool holds no liquidity yet. Try again in a moment. | The coin is between its curve and its pool, and nothing trades. retryable: true, retryAfterSeconds: 15. | POST /v1/trade/build |
QUOTE_TOO_SMALL | 422 | This amount is too small to trade after fees. The first buy is too small or above what the curve can fill. | The amount buys or returns nothing once fees are taken; or a first buy is outside what a new curve fills. | POST /v1/trade/build, POST /v1/launch/build |
IMAGE_INVALID | 400 | Choose a PNG, JPG, GIF, WEBP image. The file contents do not match its image type. | The file's first bytes are none of the four formats, or differ from the type the upload declared. | POST /v1/metadata |
IMAGE_TOO_LARGE | 413 | Choose an image no larger than 5 MB. | The image is over 5 × 1024 × 1024 bytes. | POST /v1/metadata |
UPLOAD_FAILED | 502 | Pinata could not be reached. Try again. Pinata is unavailable (HTTP <status>). Try again. Pinata is rate limiting uploads. Wait a few seconds and try again. Pinata refused the upload (HTTP <status>). Pinata returned no valid content identifier. Try again. Metadata storage could not save this file. Try again. | The storage behind the upload failed. retryable is true for every message but the refusal. | POST /v1/metadata |
MINT_STOCK_EMPTY | 503 | No launch mint is ready yet. Try again in a moment. | No mint is in stock for a new coin. retryable: true, retryAfterSeconds: 30. | POST /v1/launch/build |
NOT_A_KODAMA | 409 | You are not a kodama of this tree. | The wallet has no kodama record in the tree, or, for water, no coins in it. | POST /v1/move-out/build, /v1/water/build, /v1/pick/build, /v1/claim-echo/build |
ALREADY_WATERED_TODAY | 409 | You already watered this tree today. | The wallet watered this tree in the current day. | POST /v1/water/build |
NO_COINS_COUNTING_TODAY | 409 | You have no coins counting today. | Every coin the wallet has in the tree was moved in today. Coins moved in today count from tomorrow. | POST /v1/water/build |
NOTHING_TO_PICK | 409 | There is no fruit ready to pick. | The wallet has no fruit ready in the tree. | POST /v1/pick/build |
AMOUNT_ABOVE_COINS_IN_TREE | 422 | This amount is above your coins in the tree. | A move out asks for more coins than the wallet has in the tree. | POST /v1/move-out/build |
NOT_THE_PLANTER | 403 | You are not the planter of this tree. | The wallet did not plant the tree; or preparedMint names a tree another wallet prepared. | POST /v1/claim/build, POST /v1/launch/build |
NOTHING_TO_CLAIM | 409 | There is no planter share to claim. | The tree holds no planter's share waiting. | POST /v1/claim/build |
NOTHING_TO_CLAIM_ECHO | 409 | There is no echo share ready to claim. | The wallet has no payable echo share in the tree and none the tree's reserve can assign. | POST /v1/claim-echo/build |
The eight codes from NOT_A_KODAMA to NOTHING_TO_CLAIM_ECHO are also the kodama program's own refusals. A build route answers them with the stage build when it sees the fault in the tree's state before building. When the program itself refuses, in the simulation of a build or of a submitted transaction, the code is the same, the stage is simulation, error.message is the program's message and programError names the program. The program's errors are listed in Program errors.
| Program error | API code |
|---|---|
NotAKodama | NOT_A_KODAMA |
AlreadyWateredToday | ALREADY_WATERED_TODAY |
NoCoinsCountingToday | NO_COINS_COUNTING_TODAY |
NothingToPick | NOTHING_TO_PICK |
AmountAboveCoinsInTree | AMOUNT_ABOVE_COINS_IN_TREE |
NotThePlanter | NOT_THE_PLANTER |
NothingToClaim | NOTHING_TO_CLAIM |
NothingToClaimEcho | NOTHING_TO_CLAIM_ECHO |
Any other program error, from the kodama program, Raydium LaunchLab, the pool or the token program, is CHAIN_REFUSED.
Stages
error.stage says where in the flow a request failed.
stage | The failure is in |
|---|---|
validation | The request itself: its fields, its content type, its size, its origin, its rate. |
auth | Signing in. Only UNAUTHORIZED carries it. |
read | Reading: an unknown coin, the RPC, anything unexpected. |
upload | The metadata upload. |
build | Building a transaction: the platform is waiting, the tree's state refuses the action, the quote is too small. |
wallet | The signed copy the wallet returned. |
co_sign | The server's co-signature of a plant. |
simulation | The simulation of the transaction, by a program or by the chain. |
send | Sending: the order of a list, a build already submitted. |
confirmation | Following a build id that does not exist. |
A transaction that fails after it was sent is not an error response. It is the error of its status, which has its own stages.
Validation messages
VALIDATION_ERROR answers Check the highlighted fields. with fieldErrors when a schema refuses the input. fieldErrors is keyed by the field's path, and by form for a path value or an unknown key:
curl -X POST https://api.kodama.example/v1/water/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"mints": [
"HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU",
"HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU"
]
}'{
"error": {
"code": "VALIDATION_ERROR",
"message": "Check the highlighted fields.",
"retryable": false,
"stage": "validation",
"fieldErrors": {
"mints": [
"Name each tree once."
]
}
}
}Its other messages come without fieldErrors, except the three about a metadata part, which name the part:
| Message | Stage | Route |
|---|---|---|
The JSON body is invalid. | validation | Every POST route with a JSON body |
Attach the image file. | validation | POST /v1/metadata |
Send the text fields as JSON in `info`. | validation | POST /v1/metadata |
The info field is not valid JSON. | validation | POST /v1/metadata |
This tree has already been planted. | build | POST /v1/launch/build |
This transaction needs the server signature; it cannot be sent by the wallet. | co_sign | Submit |
Use the relay for a dependent transaction so it can be simulated after the previous one confirms. | send | Submit |
Confirm the previous transaction before sending this one. (retryable: true) | send | Submit |
The wallet returned bytes that are not a transaction. | wallet or co_sign | Submit |
The signed transaction is larger than a packet. | wallet or co_sign | Submit |
The wallet changed the fee payer. | wallet or co_sign | Submit |
The fee payer signature is missing or invalid. | wallet or co_sign | Submit |
The action instruction is missing from the signed transaction. | wallet | Submit |
The signed transaction calls <program>, which this action does not use. | wallet | Submit |
The wallet changed what the co-signature authorizes (<what>). Build again and sign the new copy. | co_sign | Submit |
A lookup table in the signed transaction is unavailable. | wallet or co_sign | Submit |
The signed transaction references accounts its lookup tables do not hold. | wallet or co_sign | Submit |
The stage is co_sign when the build is co-signed, wallet otherwise.
Not found messages
| Message | Stage | Route |
|---|---|---|
This API route was not found. | read | Any path that is no route |
No coin with this mint was launched on this platform. | read | GET /v1/coins/:mint, its holders, kodama and days |
This coin was just launched and is being indexed. (retryable: true, retryAfterSeconds: 3) | read | The same four |
No tree exists for this mint. | build | POST /v1/trade/build and the six tree action builds |
This coin was not launched on this platform. | build | POST /v1/trade/build |
No prepared tree exists for this mint. | build | POST /v1/launch/build with preparedMint |
This transaction was not built here, or it has been forgotten. Build it again. (retryable: true) | build | Submit |
Unknown transaction. | confirmation | GET /v1/transactions/:id |
No such file. | read | GET /media/:name |
A coin's trades and candles, and every wallet read, answer empty lists for an address they do not know, not NOT_FOUND.
Handle an error
curl -X POST https://api.kodama.example/v1/claim/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
}'import { ApiClientError, createClient, type ErrorCode } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const wait = (seconds: number) => new Promise((resolve) => setTimeout(resolve, seconds * 1_000))
async function buildClaim(wallet: string, mint: string) {
for (;;) {
try {
return await api.buildClaim({ wallet, mint })
} catch (error) {
if (!(error instanceof ApiClientError)) throw error
const { retryable, retryAfterSeconds } = error.body.error
const code = error.code as ErrorCode
if (code === 'NOT_THE_PLANTER' || code === 'NOTHING_TO_CLAIM') return null
if (!retryable) throw error
await wait(retryAfterSeconds ?? 2)
}
}
}{
"error": {
"code": "NOT_THE_PLANTER",
"message": "You are not the planter of this tree.",
"retryable": false,
"stage": "build"
}
}