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.

JSON
{
  "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.

CodeHTTPMessageRaised whenRoutes
VALIDATION_ERROR400Check the highlighted fields. with fieldErrors, or a sentence naming the faultA 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
UNAUTHORIZED401Sign in to continue.No route returns it: the API has no sign-in.None
ORIGIN_NOT_ALLOWED403This origin is not allowed.The request's Origin header is not in the service's allowed origins.Every route
NOT_FOUND404By route, listed belowThe 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_UNAVAILABLE409The 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_REQUIRED409A message naming what the upload is waiting on.Metadata storage cannot take the upload at this moment. Retry later.POST /v1/metadata
IDEMPOTENCY_CONFLICT409This transaction was already submitted.The build was submitted before under another idempotencyKey.POST /v1/transactions/submit
TRANSACTION_EXPIRED409This 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_LARGE413The request body is too large.The body is over 8,388,608 bytes.Every POST route
UNSUPPORTED_MEDIA_TYPE415Send 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_FAILED422The chain refused this transaction., or the fault's own sentenceA 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_REFUSED422The 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_LIMITED429Too 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_ERROR500The request could not be completed.Anything the service did not expect. retryable: true, with requestId to quote.Every route
UPSTREAM_UNAVAILABLE502The 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_COMPLETE409This 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_SMALL422This 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_INVALID400Choose 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_LARGE413Choose an image no larger than 5 MB.The image is over 5 × 1024 × 1024 bytes.POST /v1/metadata
UPLOAD_FAILED502Pinata 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_EMPTY503No 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_KODAMA409You 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_TODAY409You already watered this tree today.The wallet watered this tree in the current day.POST /v1/water/build
NO_COINS_COUNTING_TODAY409You 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_PICK409There is no fruit ready to pick.The wallet has no fruit ready in the tree.POST /v1/pick/build
AMOUNT_ABOVE_COINS_IN_TREE422This 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_PLANTER403You 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_CLAIM409There is no planter share to claim.The tree holds no planter's share waiting.POST /v1/claim/build
NOTHING_TO_CLAIM_ECHO409There 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 errorAPI code
NotAKodamaNOT_A_KODAMA
AlreadyWateredTodayALREADY_WATERED_TODAY
NoCoinsCountingTodayNO_COINS_COUNTING_TODAY
NothingToPickNOTHING_TO_PICK
AmountAboveCoinsInTreeAMOUNT_ABOVE_COINS_IN_TREE
NotThePlanterNOT_THE_PLANTER
NothingToClaimNOTHING_TO_CLAIM
NothingToClaimEchoNOTHING_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.

stageThe failure is in
validationThe request itself: its fields, its content type, its size, its origin, its rate.
authSigning in. Only UNAUTHORIZED carries it.
readReading: an unknown coin, the RPC, anything unexpected.
uploadThe metadata upload.
buildBuilding a transaction: the platform is waiting, the tree's state refuses the action, the quote is too small.
walletThe signed copy the wallet returned.
co_signThe server's co-signature of a plant.
simulationThe simulation of the transaction, by a program or by the chain.
sendSending: the order of a list, a build already submitted.
confirmationFollowing 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:

Shell
curl -X POST https://api.kodama.example/v1/water/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "mints": [
      "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU",
      "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU"
    ]
  }'
JSON
{
  "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:

MessageStageRoute
The JSON body is invalid.validationEvery POST route with a JSON body
Attach the image file.validationPOST /v1/metadata
Send the text fields as JSON in `info`.validationPOST /v1/metadata
The info field is not valid JSON.validationPOST /v1/metadata
This tree has already been planted.buildPOST /v1/launch/build
This transaction needs the server signature; it cannot be sent by the wallet.co_signSubmit
Use the relay for a dependent transaction so it can be simulated after the previous one confirms.sendSubmit
Confirm the previous transaction before sending this one. (retryable: true)sendSubmit
The wallet returned bytes that are not a transaction.wallet or co_signSubmit
The signed transaction is larger than a packet.wallet or co_signSubmit
The wallet changed the fee payer.wallet or co_signSubmit
The fee payer signature is missing or invalid.wallet or co_signSubmit
The action instruction is missing from the signed transaction.walletSubmit
The signed transaction calls <program>, which this action does not use.walletSubmit
The wallet changed what the co-signature authorizes (<what>). Build again and sign the new copy.co_signSubmit
A lookup table in the signed transaction is unavailable.wallet or co_signSubmit
The signed transaction references accounts its lookup tables do not hold.wallet or co_signSubmit

The stage is co_sign when the build is co-signed, wallet otherwise.

Not found messages

MessageStageRoute
This API route was not found.readAny path that is no route
No coin with this mint was launched on this platform.readGET /v1/coins/:mint, its holders, kodama and days
This coin was just launched and is being indexed. (retryable: true, retryAfterSeconds: 3)readThe same four
No tree exists for this mint.buildPOST /v1/trade/build and the six tree action builds
This coin was not launched on this platform.buildPOST /v1/trade/build
No prepared tree exists for this mint.buildPOST /v1/launch/build with preparedMint
This transaction was not built here, or it has been forgotten. Build it again. (retryable: true)buildSubmit
Unknown transaction.confirmationGET /v1/transactions/:id
No such file.readGET /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

Shell
curl -X POST https://api.kodama.example/v1/claim/build \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
    "mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
  }'
JSON
{
  "error": {
    "code": "NOT_THE_PLANTER",
    "message": "You are not the planter of this tree.",
    "retryable": false,
    "stage": "build"
  }
}

Where to go next