Error Reference

Learn about the error codes you may receive along with some tips for addressing them

Overview

Shinami APIs use the JSON-RPC 2.0 standard. JSON-RPC error codes you may receive when interacting with our services are listed below, along with service-specific errors. Additionally, our services return standard HTTP codes which are also displayed below.


General Error Codes

HTTP Errors

All of our services return standard HTTP codes including (but not limited to):

CodeHTTP MeaningNotes
400Bad RequestCheck your request to ensure it's properly formatted.
401UnauthorizedWhen you create an API Access Key, you give it rights to one or more services. Confirm you're using a non-disabled Access Key value with rights for the service(s) you're interacting with.
500Internal Server ErrorWe're unable to process your request right now. Get in touch with us if you see this.

Too Many Requests: When you hit a rate limit, we return a HTTP 200 code with a JSON-RPC error code -32010 in the response body (see in the next section). The one exception is our WebSocket API, which returns HTTP 429 when you try to open a new connection but have already reached your maximum number of connections.

JSON-RPC Errors

For JSON-RPC errors, Shinami returns HTTP 200 with the JSON-RPC error in the JSON response. Common errors across our services include:

Error CodeError TypeNotes
-32000 to -32099Server errorRead the error message for more information.
-32002Client fault error during transaction executionExamples include not enough gas, an invalid signature (sender signature provided during execution is for a different address than the sender address in the transaction block, sponsor signature provided is for a different address than the owner of the Gas Object, etc), issues with locked objects, and invalid (objectID, version) pairs. Read the error message for more information.
-32010Too many requestsYou may have exceeded your QPS rate limit. We recommend implementing retries with a backoff to deal with any rate limits you encounter. For Node Service, you may have also hit your daily request cap if you're on our Free plan. If so, you can upgrade to a Growth plan in your Shinami dashboard billing page.
-32050Transient error during transaction executionRetry the transaction. This was a transient error and the system should recover from it. One possible example is reason: JsonRpcError: Transaction timed out before reaching finality
-32600Invalid RequestThe JSON sent is not a valid request object. Double check your request formatting to ensure it's valid JSON and has all required request elements.
-32601Method not foundThe method does not exist / is not available. Double-check the method name you provided.
-32602Invalid paramsInvalid method parameter(s). Double check the count, type, and values of your request parameters. Read the error message for more information.
-32603Internal errorInternal JSON-RPC error. Read the error message for more information.
-32700Parse errorAn error occurred on the server while parsing the JSON input payload. Double-check your request. Perhaps there's an extra or missing {,},", [,], etc.

Other Errors

You may see the following errors when using our Shinami Clients SDK.

Error CodeMessageNotes
7979Bad response formatDouble check that you're using a valid Access Key value.

Service-Specific Error Codes

WebSocket API

In addition to the general error codes listed above, the following codes are returned by our WebSocket API. Note: you may see additional errors beyond what's listed below.

HTTP Codes

This is the one Shinami service that returns HTTP 429 for rate-limit errors. It connotes that you cannot create additional connections to the service because you have reached your maximum allowed.

CodeHTTP MeaningNotes
429Too Many RequestsClose one of your existing connections on the network if you need to open a new one.

JSON-RPC Errors

Error CodeError MessageNotes
-32000"Request size too large"Send a smaller request. This is an unlikely error with normal use of this API. You may have accidentally constructed a massive suix_subscribeEventor suix_subscribeTransaction filter.
-32010"Too many subscriptions"This could be because you've hit your total subscription limit for a network or your limit for an individual access key. Unsubscribe from one of your existing subscriptions or adjust your key's settings.

Gas Station API

In addition to the general error codes listed above, the following codes are returned by our Gas Station API. Note: you may see additional errors beyond what's listed below.

JSON-RPC errors

Error CodeError MessageNotes
-32602"gasBudget: {{value}} out of range"You requested a gas budget either lower than the minimum amount required to pay for a transaction, or far larger than needed. Please set a GAS_BUDGET that will cover the expect cost plus a small margin. See here for tips.
-32602"GasCoin argument not allowed for sponsorship."In a sponsored transaction, you cannot use the gas object provided by Shinami for other purposes. For example, you cannot write const [coin] = txb.splitCoins(txb.gas,[txb.pure(100)]); because it's accessing txb.gas.

Other errors

Error CodeError MessageNotes
-1"Gas object unavailable"We had an issue processing the request. Try again at a later time, or try with a smaller gas budget.
-2"Insufficient fund balance"Add extra SUI to your fund balance. See our FAQ for guidance on how to deposit SUI into your fund.

Invisible Wallet API errors

In addition to the general error codes listed above, the following codes are returned by our Invisible Wallet API. Note: you may see additional errors beyond what's listed below.

JSON-RPC errors

Error CodeError MessageNotes
-32003"Make sure the key you are using has access to the required services"The access key you are using does not have access to all the Shinami services the request interacts with. Make sure that the key you use has Gas Station and/or Node rights in addition to Invisible Wallet rights if needed.
-32003"Access key not associated with a network"Wallet access keys are not associated with a network and work with all networks (Devnet, Testnet, Mainnet). Node and Gas Station keys are, however, so when using Wallet Service requests that require Node and/or Gas Station access, make sure that the access key you're using has rights to those services on the network you're using. For guidance on how to set up an access key with rights to all services see our FAQ .
-32602"Wallet ID not found"Confirm you're using a walletId value that you've used in a successful call to shinami_wal_createWallet (as this suggests you haven't created an Invisible Wallet with this id yet.).
-32602"Failed to decrypt wallet key"Successful decryption requires pairing a walletId with a sessionToken generated by the secret used when creating the wallet. Confirm that you're using the secret that was used to generate a sessionId when creating this wallet.
-32602"Wallet ID already exists, use 'getWallet' to retrieve the address"You've already created a wallet using this walletID. Use shinami_wal_getWallet to look up the wallet's Sui address if desired.
-32602"Bad session token"The sessionToken has expired or is not parseable. Ensure you're correctly passing a sessionToken value that has not expired.
-32602Beneficiary graph error messages include:
"Failed to build tx. Please double check beneficiaryGraphId", "Non-existing beneficiaryGraphId",
"beneficiaryGraphId not an object", "Invalid data for beneficiaryGraphId"
Confirm that you are using the correct object id of a beneficiary graph that currently exists to the network you're making a request to (try looking it up in the Sui Explorer for that network).

zkLogin wallet API errors

In addition to the general error codes listed above, the following codes are returned by our zkLogin wallet API. Note: you may see additional errors beyond what's listed below.

JSON-RPC errors

Error CodeError Message ExampleNotes
-32602"The issuer {{issuer name}} is not supported"Use an OAuth provider from the list of supported providers.
-32602"Bad jwt. The Token has expired on 2023-11-08T23:52:00Z."Ensure you're using a non-expired JWT.
-32602"Nonce TjpyZAr252rQ8dzOwoA1vioMTzY does not match computed nonce LAo4DvFaHZ88kREHZmRqgz8EBVw"Ensure that the jwtRandomness value was the same one used to prepare the nonce from the OAuth flow that generated the jwt that's also being passed to the function.

Example JSON-RPC Errors

Below are two example JSON-RPC error responses using cURL and our Shinami Clients TypeScript SDK. Replace all instances of {{name}} with the actual value for that name

// Here, we've mistyped the name of the suix_getReferenceGasPrice method
curl https://api.shinami.com/node/v1 \
-X POST \
-H 'X-API-Key: {{nodeServiceAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{ 
        "jsonrpc":"2.0", 
        "method":"getReferenceGasPrice", 
        "params":[], 
        "id":1
    }'

// Response:
{
   "error" : {
      "code" : -32601,
      "message" : "Method not found"
   },
   "id" : 1,
   "jsonrpc" : "2.0"
}
// Here, we are making a request to Shinami Gas Station for transaction 
//  sponsorship with a value of 1 MIST. This is too low to have a chance 
//  of success, so we get a -32602 Invalid params error
import { GasStationClient } from "@shinami/clients";

const gasClient = new GasStationClient({{gasStationAccessKey}});

await gasClient.sponsorTransactionBlock(
  {{transactionToSponsor}},
  {{senderAddress}},
  1 // 1 MIST 
);

// Response:
JSONRPCError: Invalid params
    at new JSONRPCError... {
  code: -32602,
  data: { details: 'gasBudget: 1 out of range' }
}