Error Reference - Shinami Developer Documentation

Overview

Shinami APIs generally use the JSON-RPC 2.0 standard. HTTP and JSON-RPC error codes you may receive when interacting with our services are listed below, along with service-specific errors. We have a lot of helpful content below, but if you don’t find an answer to your question you can reach out to us.

General Error Codes

HTTP Errors

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

Code	HTTP Meaning	Notes	Services
400	Bad Request	Check your request to ensure it’s properly formatted.	All
401	Unauthorized	When you create an API Access Key, you give it rights to one or more services. Confirm that you’ve correctly copied the value of an Access Key with rights for the service(s) you’re trying to use. Confirm that the key has not been disabled. If you have an IP and/or domain whitelist/allowlist for the key, ensure that the IP and/or domain of the requests you’re sending matches an entry in the list(s). It can be good to test first with empty allowlists - so all requests with the API key are accepted - and then add values later if desired, once you know everything is working.	All
500	Internal Server Error	We’re unable to process your request right now. You may occasionally see a few of these in the course of normal operations, and a retry will often succeed. However, you should not see these consistently or in a large amount. Get in touch with us if you do.	All

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 Code	Error Type	Notes
-32000 to -32099	Server error	Read the error message for more information.
-32010	Too many requests	You may have exceeded your QPS rate limit. We recommend implementing retries with a backoff to deal with any rate limits you encounter.
-32012	Resource Limit Exceeded	You have reached your quota for the given operation for the current time period. Do not retry the operation in the same time period as you will get the same response. For example, you surpassed our Sui zkLogin API’s cap of two proofs per address per minute. If you’re unclear on the limit you reached or want to discuss the possibility of raising it, reach out to `support@shinami.com`.
-32600	Invalid Request	The 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.
-32601	Method not found	The method does not exist / is not available. Double-check the method name you provided.
-32602	Invalid params	Invalid method parameter(s). Double check the count, type, and values of your request parameters. Read the error message for more information.
-32603	Internal error	Internal JSON-RPC error. Read the error message for more information.
-32700	Parse error	An 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 Code	Message	Notes
7979	Bad response format	This is a code our SDK returns in some cases in place of an HTTP 401. If you get this, double check that you’re using a valid, enabled access key value. If you have any domain or IP allowlists on the key, make sure you are matching them with your request. It can be good to test first with empty allowlists - so all requests with the API key are accepted - and then add values later if desired, once you know everything is working.

Aptos: service-specific error codes

Aptos Gas Station API

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

Error Code	Error Message	Notes
-32602	”expirationTimestampSecs out of range”	Make sure that your transaction expiration timestamp is not in the past and is less than one hour from now.
-32602	”Wrong chainId”	Our Aptos Gas Station works on Testnet (`chainId: 2`) and Mainnet (`chainId: 1`). Make sure you’re setting the appropriate chainId.
-32602	”gasUnitPrice out of range”	Make sure you’re using a price per gas unit that is within the minimum and maximum allowed values. For more info, see here.
-32602	”maxGasAmount out of range”	Make sure you’re using a max gas amount that is within the minimum and maximum allowed values. For more info, see here.
-32602	”Stale sequenceNumber”	Make sure you’re using a sequence number for the transaction that is the equal to or greater than the account’s current on-chain sequence number.
-32602	”Bad rawTransaction bytes”	Ensure you’re sending a successfully constructed transaction in the format our API expects.

Other errors

Error Code	Error Message	Notes
-1	”No active fund”	You need an active Gas Station fund tied to the access key you’re using in order to successfully sponsor a transaction.
-2	”Insufficient fund balance”	The Gas Station fund tied to the API access key you used does not have sufficient APT to sponsor this transaction. This could be due in part to tying up unnecessarily large amount of APT in active sponsorships. For that, we recommend setting gas budgets that are enough to execute your transactions with just a small buffer added. For guidance on how to deposit APT into your fund, see the Aptos Gas station page of our Help Center.
-3	”Transaction submission failed”	Read the error message for additional information.

Aptos Invisible Wallet API

In addition to the general error codes listed above, the following codes are returned by our Invisible Wallet API. Invisible Wallet requests that require an access key with Gas Station rights can also return any of the Aptos Gas Station errors, as we’ll propagate those back to you if there is a Gas Station error as a part of processing your request. Note that you may see additional errors beyond what’s listed below. JSON-RPC errors

Error Code	Error Message	Notes
-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 Gas Station rights in addition to Invisible Wallet rights if needed.
-32602	”Wallet ID not found”	Confirm you’re using a `walletId` value that you’ve used to successfully create a wallet (as this suggests you haven’t created an Invisible Wallet with this id yet.).
-32012	Resource Limit Exceeded	You have reached the maximum number of wallets you can create this month for Aptos. Do not retry on this error. Other wallet operations will still work, like signing with wallets you’ve already created. If you need to create more wallets this month reach out to `support@shinami.com` to discuss an Enterprise wallet plan that fits your needs.
-32013	”Wallet ID already exists, use ‘getWallet’ to retrieve the address”	You have already created (and possibly initialized) a wallet with this walletId.
-32013	”Wallet ID already exists, use ‘initializeWalletOnChain’ to initialize for a specific network”	As the error message states, you can use `initializeWalletOnChain` with the walletID, or simply use the walletID in a transaction with `executeGaslessTransaction` and it will be initialized in the process.
-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	”Bad session token”	The sessionToken has expired or is not parseable. Ensure you’re correctly passing a sessionToken value that has not expired.

Example JSON-RPC Errors

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

// Unfortunately, this is not a method we support, :(
curl https://api.us1.shinami.com/aptos/gas/v1 \
-X POST \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc":"2.0",
        "method":"getAMilkshakeAndFries",
        "params":[],
        "id":1
}'

// Response:
{
   "error" : {
      "code" : -32601,
      "message" : "Method not found"
   },
   "id" : 1,
   "jsonrpc" : "2.0"
}

import { GasStationClient } from "@shinami/clients/aptos";
const gasStationClient = new GasStationClient("YOUR_API_KEY");

const transaction = // build a tranasaction where
                    // transaction.rawTransaction.expiration_timestamp_secs
                    // is set in the past, or more than an hour in the future

await gasStationClient.sponsorTransaction(transaction);

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

Movement: service-specific error codes

Movement Gas Station API

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

Error Code	Error Message	Notes
-32602	”expirationTimestampSecs out of range”	Make sure that your transaction expiration timestamp is not in the past and is less than one hour from now.
-32602	”Wrong chainId”	Our Movement Gas Station works on Testnet and Mainnet. Make sure you’re setting the appropriate chainId.
-32602	”gasUnitPrice out of range”	Make sure you’re using a price per gas unit that is within the minimum and maximum allowed values. For more info, see here.
-32602	”maxGasAmount out of range”	Make sure you’re using a max gas amount that is within the minimum and maximum allowed values. For more info, see here.
-32602	”Stale sequenceNumber”	Make sure you’re using a sequence number for the transaction that is the equal to or greater than the account’s current on-chain sequence number.
-32602	”Bad rawTransaction bytes”	Ensure you’re sending a successfully constructed transaction in the format our API expects.

Other errors

Error Code	Error Message	Notes
-1	”No active fund”	You need an active Gas Station fund tied to the access key you’re using in order to successfully sponsor a transaction.
-2	”Insufficient fund balance”	The Gas Station fund tied to the API access key you used does not have sufficient MOVE to sponsor this transaction. This could be due in part to tying up unnecessarily large amount of MOVE in active sponsorships. For that, we recommend setting gas budgets that are enough to execute your transactions with just a small buffer added. For guidance on how to deposit MOVE into your fund, see the Movement Gas station page of our Help Center.
-3	”Transaction submission failed”	Read the error message for additional information.

Movement Invisible Wallet API

In addition to the general error codes listed above, the following codes are returned by our Invisible Wallet API. Invisible Wallet requests that require an access key with Gas Station rights can also return any of the Movement Gas Station errors, as we’ll propagate those back to you if there is a Gas Station error as a part of processing your request. Note that you may see additional errors beyond what’s listed below. JSON-RPC errors

Error Code	Error Message	Notes
-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 Gas Station rights in addition to Invisible Wallet rights if needed.
-32602	”Wallet ID not found”	Confirm you’re using a `walletId` value that you’ve used to successfully create a wallet (as this suggests you haven’t created an Invisible Wallet with this id yet.).
-32012	Resource Limit Exceeded	You have reached the maximum number of wallets you can create this month for Movement. Do not retry on this error. Other wallet operations will still work, like signing with wallets you’ve already created. If you need to create more wallets this month reach out to `support@shinami.com` to discuss an Enterprise wallet plan that fits your needs.
-32013	”Wallet ID already exists, use ‘getWallet’ to retrieve the address”	You have already created (and possibly initialized) a wallet with this walletId.
-32013	”Wallet ID already exists, use ‘initializeWalletOnChain’ to initialize for a specific network”	As the error message states, you can use `initializeWalletOnChain` with the walletID, or simply use the walletID in a transaction with `executeGaslessTransaction` and it will be initialized in the process.
-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	”Bad session token”	The sessionToken has expired or is not parseable. Ensure you’re correctly passing a sessionToken value that has not expired.

Example JSON-RPC Errors

// Unfortunately, this is not a method we support, :(
curl https://api.us1.shinami.com/movement/gas/v1 \
-X POST \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc":"2.0",
        "method":"getAMilkshakeAndFries",
        "params":[],
        "id":1
}'

// Response:
{
   "error" : {
      "code" : -32601,
      "message" : "Method not found"
   },
   "id" : 1,
   "jsonrpc" : "2.0"
}

import { GasStationClient } from "@shinami/clients/aptos";
const gasStationClient = new GasStationClient("YOUR_API_KEY");

const transaction = // build a tranasaction where
                    // transaction.rawTransaction.expiration_timestamp_secs
                    // is set in the past, or more than an hour in the future

await gasStationClient.sponsorTransaction(transaction);

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

Sui: service-specific error codes

Sui Gas Station API

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

Error Code	Error Message	Notes
-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 Code	Error Message	Notes
-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. This could be due in part to tying up unnecessarily large amounts of SUI in existing sponsorships. For that, we recommend using our auto-budgeting feature. For guidance on how to deposit SUI into your fund, see the Sui Gas Station page of our Help Center .

Sui Invisible Wallet API

In addition to the general error codes listed above, the following codes are returned by our Invisible Wallet API. Invisible Wallet requests that require an access key with Gas Station rights can also return any of the Sui Gas Station errors, as we’ll propagate those back to you if there is a Gas Station error as a part of processing your request. Note that you may see additional errors beyond what’s listed below. JSON-RPC errors

Error Code	Error Message	Notes
-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 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 (Testnet, Mainnet). Gas Station keys are, however, so when using Wallet Service requests that require 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 Authentication and API Keys guide.
-32012	Resource Limit Exceeded	You have reached the maximum number of wallets you can create this month for Sui (across both Invisible and zkLogin Wallets). Do not retry on this error. Other wallet operations will still work, like signing with wallets you’ve already created. If you need to create more wallets this month reach out to `support@shinami.com` to discuss an Enterprise wallet plan that fits your needs.
-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.
-32602	Beneficiary 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).

Sui zkLogin wallet API

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

Error Code	Error Message Example	Notes
-32012	”Resource Limit Exceeded”	Returned on `shinami_zkp_createZkLoginProof` requests. You have exceed the zk proof generation cap of 2 per address per minute. Do not immediately retry. Wait up to a minute and try again. Returned on `shinami_zkw_getOrCreateZkLoginWallet` requests. You have reached the maximum number of wallets you can create this month for Sui (across both zkLogin and Invisible Wallets). Do not retry on this error. Other wallet operations will still work, like fetching the salt for wallets you’ve already created. If you need to create more wallets this month reach out to `support@shinami.com` to discuss an Enterprise wallet plan that fits your needs.
-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`, `ephemeralKeyPair`, and `maxEpoch` values passed to `shinami_zkp_createZkLoginProof` are the ones used to prepare the nonce from the OAuth flow that generated the `jwt` that’s also being passed to the function.
-32602	`{"name":"InputValidationError","message":"JWT randomness 8641894711085230802105740842295470710772303705 must be 16 bytes"}`	Ensure that you’re passing each parameter’s value in the expected representation. For example, our SDK’s `createZkLoginProof` method expects the `jwtRandomness` parameter as a `bigint`.

Example JSON-RPC errors

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

// Unfortunately, this is not a method we support, :(
curl https://api.us1.shinami.com/sui/gas/v1 \
-X POST \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc":"2.0",
        "method":"getAMilkshakeAndFries",
        "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/sui";

const gasClient = new GasStationClient("YOUR_API_KEY");

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

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

​Overview

​General Error Codes

​HTTP Errors

​JSON-RPC Errors

​Other Errors

​Aptos: service-specific error codes

​Aptos Gas Station API

​Aptos Invisible Wallet API

​Example JSON-RPC Errors

​Movement: service-specific error codes

​Movement Gas Station API

​Movement Invisible Wallet API

​Example JSON-RPC Errors

​Sui: service-specific error codes

​Sui Gas Station API

​Sui Invisible Wallet API

​Sui zkLogin wallet API

​Example JSON-RPC errors

Overview

General Error Codes

HTTP Errors

JSON-RPC Errors

Other Errors

Aptos: service-specific error codes

Aptos Gas Station API

Aptos Invisible Wallet API

Example JSON-RPC Errors

Movement: service-specific error codes

Movement Gas Station API

Movement Invisible Wallet API

Example JSON-RPC Errors

Sui: service-specific error codes

Sui Gas Station API

Sui Invisible Wallet API

Sui zkLogin wallet API

Example JSON-RPC errors