Errors

Every error has a stable code, an HTTP status and a link back to this page.

Error shape

REST calls return the status code and a JSON body.

REST

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 1 s.",
    "status": 429,
    "docs": "https://tide.ad/docs/errors#rate_limited"
  }
}

JSON-RPC calls return the error object in the body. The stable code is in error.data.code.

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32429,
    "message": "Too many requests. Retry in 1 s.",
    "data": { "code": "rate_limited", "docs": "https://tide.ad/docs/errors#rate_limited" }
  }
}

Match on code, not on the message. New codes may be added. A code never changes meaning. JSON-RPC also uses -32600 for an invalid request.

Codes

Code	HTTP	JSON-RPC
invalid_params	400	-32602
unauthorized	401	-32401
forbidden_origin	403	-32403
out_of_credits	402	-32402
rate_limited	429	-32429
not_found	404	-32004
not_indexed	404	-32004
not_implemented	501	-32601
upstream_busy	503	-32503
would_fail	422	-32010
unsafe	422	-32011
rejected	422	-32002
method_not_found	404	-32601
internal	500	-32000

invalid_params

HTTP 400. JSON-RPC -32602. A parameter is missing, has the wrong type or is out of range. The message names the parameter.

Check the parameters table on the method page and send the call again.

unauthorized

HTTP 401. JSON-RPC -32401. The key is missing where one is required, or it is not a valid key.

Send a valid key in x-api-key, in the api-key query parameter or as a bearer token. Check that the key was not revoked.

forbidden_origin

HTTP 403. JSON-RPC -32403. The call came from an origin or IP the key does not allow.

Add the origin or IP to the key's allowed list under API keys, or call from an allowed place.

out_of_credits

HTTP 402. JSON-RPC -32402. The key has used all of its credits for the month (keyless: for the day).

Top up with USDC (see Pay with USDC on Plans and pricing), pay for the call through its 402 offer, wait for the reset on the 1st, or move to a paid plan through the tide Telegram, t.me/tide_sui. Errors never cost credits.

rate_limited

HTTP 429. JSON-RPC -32429. Too many requests a second for the key's plan and rate class.

Wait the number of seconds in the retry-after header, then retry with backoff. Batch where the method allows it.

not_found

HTTP 404. JSON-RPC -32004. The thing you asked for does not exist: an unknown digest, object, address history or name.

Check the id. New transactions can take about a second to appear.

not_indexed

HTTP 404. JSON-RPC -32004. The index does not cover the range you asked for yet. The error data holds the lowest checkpoint it can answer from.

Ask for a later range, or use the checkpoint in the error data as your lower bound.

not_implemented

HTTP 501. JSON-RPC -32601. The method exists in the registry but is not live yet.

It is on the roadmap. Check the method page for its phase.

upstream_busy

HTTP 503. JSON-RPC -32503. The service is shedding load. Keyless and Free calls are shed first.

Retry after a few seconds with backoff. A paid key is shed last.

would_fail

HTTP 422. JSON-RPC -32010. tx.build made the transaction, but the dry run on current mainnet state says it would fail or be rejected (for example the wallet is short of the coin). No bytes are returned. The error data holds the check with the reason.

Read error.data.check.error.sentence, fix the input (a smaller amount, another coin) and build again.

unsafe

HTTP 422. JSON-RPC -32011. tx.build made the transaction, but the pre-sign check says danger. No bytes are returned. The error data holds the check with its findings.

Read the findings in error.data.check. Do not work around them; pick another venue or coin.

rejected

HTTP 422. JSON-RPC -32002. POST /v0/transactions/send (or sui_executeTransactionBlock): the network refused the transaction before running it, so nothing changed and no gas was charged. error.data has the digest, a reason (SIGNATURE_INVALID, GAS_BALANCE_TOO_LOW, GAS_BUDGET_TOO_LOW, GAS_PRICE_TOO_LOW, OBJECT_LOCKED, OBJECT_VERSION_UNAVAILABLE, OBJECT_NOT_FOUND, EXPIRED, ADDRESS_DENIED, TOO_LARGE or REJECTED) and the network's own message.

Fix what the reason names, rebuild and sign again. A transaction that ran and failed is not this error: it is a 200 with status failure.

method_not_found

HTTP 404. JSON-RPC -32601. No method or path has that name.

Check the spelling against the method list. Names are case sensitive.

internal

HTTP 500. JSON-RPC -32000. Something failed on our side.

Retry once. If it keeps failing, send us the x-request-id header of the response.