Overview

Shinami APIs generally use the JSON-RPC 2.0 standard, with the exception of Aptos Fullnode REST and Indexer GraphQL APIs. 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):

  <th>
    HTTP Meaning
  </th>

  <th>
    Notes
  </th>

  <th>
    Services
  </th>
</tr>

  <td>
    Bad Request
  </td>

  <td>
    Check your request to ensure it's properly formatted.
  </td>

  <td>
    All
  </td>
</tr>

<tr>
  <td>
    401
  </td>

  <td>
    Unauthorized
  </td>

  <td>
    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](https://app.shinami.com/access-keys) with rights for the service(s) you're trying to use. Confirm that the key has not been disabled.  

    When you create an API access key, you also create it in a specific geographic region (e.g. `US East - us1`). Make sure that you're using the region URL with an API key created in that region.  

    If you have an [IP or domain whitelist for the key](https://docs.shinami.com/docs/authentication-and-api-keys#sender-domain-and-ip-address-allowlists), ensure that the IP / domain of the requests you're sending matches the whitelist.
  </td>

  <td>
    All
  </td>
</tr>

<tr>
  <td>
    429
  </td>

  <td>
    Too Many Requests
  </td>

  <td>
    Build in a retry with a backoff.
  </td>

  <td>
    Aptos Fullnode REST and Indexer GraphQL APIs, plus Sui Websocket Service. For other services we return an HTTP 200 and a JSON-RPC code of `-32010`(see next section).
  </td>
</tr>

<tr>
  <td>
    500
  </td>

  <td>
    Internal Server Error
  </td>

  <td>
    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.
  </td>

  <td>
    All
  </td>
</tr>

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:

  <th>
    Error Type
  </th>

  <th>
    Notes
  </th>
</tr>

  <td>
    Server error
  </td>

  <td>
    Read the error message for more information.
  </td>
</tr>

<tr>
  <td>
    \-32010
  </td>

  <td>
    Too many requests
  </td>

  <td>
    You may have exceeded your QPS rate limit. We recommend implementing retries with a backoff to deal with any rate limits you encounter. 
  </td>
</tr>

<tr>
  <td>
    \-32012
  </td>

  <td>
    Resource Limit Exceeded
  </td>

  <td>
    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. Or, you have reached the Sui Node free plan's daily request cap. If you're unclear on the limit you reached or want to discuss the possibility of raising it, reach out to `[email protected]`.
  </td>
</tr>

<tr>
  <td>
    \-32600
  </td>

  <td>
    Invalid Request
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    \-32601
  </td>

  <td>
    Method not found
  </td>

  <td>
    The method does not exist / is not available. Double-check the method name you provided.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    Invalid params
  </td>

  <td>
    Invalid method parameter(s). Double check the count, type, and values of your request parameters. Read the error message for more information.
  </td>
</tr>

<tr>
  <td>
    \-32603
  </td>

  <td>
    Internal error
  </td>

  <td>
    Internal JSON-RPC error. Read the error message for more information.
  </td>
</tr>

<tr>
  <td>
    \-32700
  </td>

  <td>
    Parse error
  </td>

  <td>
    An error occurred on the server while parsing the JSON input payload. Double-check your request. Perhaps there's an extra or missing `{`,`}`,`"`, `[`,`]`, etc.
  </td>
</tr>

Other Errors

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

Aptos: Service-Specific Error Codes

Aptos Full node REST API

Our Aptos Full node REST API returns standard HTTP codes as mentioned above. Full node error responses will often also include Aptos errors, which can be found here. Read more about Aptos Errors, including possible vm_error cases in this doc. Make sure to check for all error codes and messages returned so that you have a better sense of the issue and how to resolve it.

Aptos REST API specific errors

Note: you may see additional errors beyond what's listed below.

  <th>
    Aptos error code
  </th>

  <th>
    Example error message and resolution notes
  </th>
</tr>

  <td>
    account\_not\_found
  </td>

  <td>
    *Example error message*\
    `"Account not found by Address( 0x94db619929656f03fe42081c3d421cdd3caa3bf5346fe8cf22d49dbfda540ea6) and Ledger version(6325040702)"`  

    *Possible causes and resolutions*\
    The account was not found on the queried network. Reasons include a typo inputting the address, querying a network where the address has not been initialized, and a race condition where the address was initialized and then you immediately queried but the Full node was not yet aware of the initialization.
  </td>
</tr>

<tr>
  <td>
    410
  </td>

  <td>
    block\_pruned
  </td>

  <td>
    *Example error message*\
    `"message": _"Block(225733446) has been pruned"`  

    *Possible causes and resolutions*\
    This block has been pruned from our nodes. As the blockchain grows (indefinitely), nodes manage the amount of storage disk space required by pruning old blockchain data. If you require regular access to historical data reach out to us at `[email protected]` and we can discuss whether a dedicated Enterprise node makes sense for you.
  </td>
</tr>

<tr>
  <td>
    404
  </td>

  <td>
    transaction\_not\_found
  </td>

  <td>
    *Example error message*\
    `"Transaction not found by Transaction hash(0xfa518597d5527bb3240524c47c6afbfc1f52c665bc35616f7eddf72b56bb778e)"`  

    *Possible causes and resolutions*\
    The transaction may not exist on the network you're querying (e..g Mainnet). Confirm the transaction hash and network are the correct values you wish you use. The transaction could be old enough that it's from a block that's pruned from our nodes.  If you require regular access to historical data reach out to us at `[email protected]` and we can discuss whether a dedicated Enterprise node makes sense for you.
  </td>
</tr>

<tr>
  <td>
    400
  </td>

  <td>
    vm\_error
  </td>

  <td>
    *Example error message*  

    ```
      data: {  
        message: 'Invalid transaction: Type: Validation Code: INVALID_AUTH_KEY',  
        error_code: 'vm_error',  
        vm_error_code: 2  
      }
    ```*Possible causes and resolutions*\
    There are a variety of Aptos vm errors. Read about codes and resolution steps [here](). In the above case, I submitted a transaction where the account that signed for it was not the sender. So, the resolution would be to ensure that the sender Account is signing the transaction.
  </td>
</tr>

Example error response

Here is an example of a partial error response where an invalid signature is used when submitting a transaction. You can see that the HTTP status is a 400 because it's a client-side error for submitting an invalid request. We also see a vm_error for an INVALID_SIGNATURE.

{ 
  ...
  status: 400,
  statusText: 'Bad Request',
  data: {
    message: 'Invalid transaction: Type: Validation Code: INVALID_SIGNATURE',
    error_code: 'vm_error',
    vm_error_code: 1
  },

Aptos Indexer GraphQL API

Our Aptos Indexer GraphQL API returns standard HTTP codes. A response that contains one or more GraphQL errors is considered a successful response and will have a HTTP 200 status code. Responses will contain GraphQL errors if any of the operations you provided ran into an issue.

Example error response

Here is an example of a partial error response where a current_coin_balances operation's selection set included a field that does not exist, called this_field_does_not_exist). Note that only the message field is required -extensions may or may not be present on an error; and, if present, may or may not contain a path or code field.

// The query
await aptosClient.queryIndexer({
  query: {
    query: `query MyQuery {
              current_coin_balances(limit: 10, where: {owner_address: {_eq: "0x239589c5cfb0cc96f76fa59165a7cbb6ef99ad50d0acc34cf3a2585d861511be"}}) {
              coin_type
              amount
              this_field_does_not_exist
            }
          }`
  }
});

// The partial error response:
...
  status: 200,
  statusText: 'OK',
  data: {
    errors: [
      {
        message: "field 'this_field_does_not_exist' not found in type: 'current_coin_balances'",
        extensions: {
          path: '$.selectionSet.current_coin_balances.selectionSet.this_field_does_not_exist',
          code: 'validation-failed'
        }
      }
    ]
  },
...

Aptos 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

Other errors

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: you may see additional errors beyond what's listed below.

JSON-RPC errors

Example JSON-RPC Errors

Below are two example requests and their assocaited 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

curl https://api.shinami.com/aptos/gas/v1 \
-X POST \
-H 'X-API-Key: {{gasStationAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc":"2.0",
        "method":"getAMilkshakeAndFries",
        "params":[
            "0x397020433ff4fd6446d9ac73b7d3fb210840168e6bfe146d1bbea21ff5b425cf00000000000000000075a11ceb0b0600000007010002030206040802050a0707110c081d20063d0a0000000101020100000001030106090000056465627567057072696e74000000000000000000000000000000000000000000000000000000000000000103080100000000000000000000070b000700160c010e013800020001010100000000000000400d03000000000064000000000000005ee543660000000002"
        ],
        "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("{{gasStationAccessKey}}");

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 Node Service: JSON-RPC API

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

  <th>
    Error Type
  </th>

  <th>
    Notes
  </th>
</tr>

  <td>
    Client fault error during transaction execution
  </td>

  <td>
    Read the error message for more information. Examples 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. Another reason and message is "The transaction is already finalized but with different user signatures." In that case, the same transaction was signed and submitted more than once with different but valid signatures (e.g. two signers that make up a 1 of 2 mulitsig address). When the transaction was submitted with the first signature it was successful, and a subsequent submission with a different signature produces this error.
  </td>
</tr>

<tr>
  <td>
    \-32010
  </td>

  <td>
    Too Many Requests
  </td>

  <td>
    You have sent more requests per second than the maximum assigned to your access key. We recommend a retry with a backoff to handle this case.
  </td>
</tr>

<tr>
  <td>
    \-32012
  </td>

  <td>
    Resource Limit Exceeded
  </td>

  <td>
    You've hit the daily Free plan request cap for this network. Don't send requests on this network again until tomorrow (0:00 UTC). If you wish to lift the cap, you can sign up for the Pay-As-You-Go tier on the "Sui Node Service" tab of the [billing page](https://app.shinami.com/billing) in your dashboard.  

    Or, you're on a paid plan and haven't paid your bill within the allotted 10 days. See here for [how to resolve it](https://docs.shinami.com/docs/sui-billing-faq#how-long-do-i-have-to-pay-my-bill-pay-as-you-go-plan).
  </td>
</tr>

<tr>
  <td>
    \-32050
  </td>

  <td>
    Transient error during transaction execution
  </td>

  <td>
    Retry the transaction (without rebuilding and resigning it). This is a transient error and the system should recover from it. There is a chance that the transaction succeeded if you get this error code, but it's safe to re-submit the exact same transaction (without rebuilding or resigning it). You also have the option to poll a Fullnode for the transaction digest. In general, for errors like this that can take up to 30s to be hit - and even the occasional high latency for some transactions - it's worth considering UI treatment to show to the user after X seconds that says something like "this transaction is taking longer to process than usual" to indicate that work is still being done.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    Invalid params
  </td>

  <td>
    In addition to the general notes from the [JSON-RPC Errors section](https://docs.shinami.com/docs/error-reference#json-rpc-errors) above, on a `sui_getTransactionBlock` this could mean that a digest either doesn't exist or has just been executed but not yet indexed by the Full nodes (which can take a couple of seconds).
  </td>
</tr>

Sui Node Service: WebSocket API (deprecated)

Note: websocket service is being retired by Mysten very soon. See the note at thetop of the API doc.

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.

JSON-RPC Errors

Sui 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

Other errors

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: you may see additional errors beyond what's listed below.

JSON-RPC errors

  <th>
    Error Message
  </th>

  <th>
    Notes
  </th>
</tr>

  <td>
    "Make sure the key you are using has access to the required services"
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    \-32003
  </td>

  <td>
    "Access key not associated with a network"
  </td>

  <td>
    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 [Authentication and API Keys guide](doc:authentication-and-api-keys). 
  </td>
</tr>

<tr>
  <td>
    \-32012
  </td>

  <td>
    Resource Limit Exceeded
  </td>

  <td>
    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 `[email protected]` to discuss an Enterprise wallet plan that fits your needs.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "Wallet ID not found"
  </td>

  <td>
    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.).
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "Failed to decrypt wallet key"
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "Wallet ID already exists, use 'getWallet' to retrieve the address"
  </td>

  <td>
    You've already created a wallet using this `walletID`. Use `shinami_wal_getWallet` to look up the wallet's Sui address if desired.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "Bad session token"
  </td>

  <td>
    The sessionToken has expired or is not parseable. Ensure you're correctly passing a sessionToken value that has not expired.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    *Beneficiary graph error messages include:*\
    "Failed to build tx. Please double check beneficiaryGraphId", "Non-existing beneficiaryGraphId",\
     "beneficiaryGraphId not an object",  "Invalid data for beneficiaryGraphId"
  </td>

  <td>
    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).
  </td>
</tr>

Sui zkLogin wallet API

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

  <th>
    Error Message Example
  </th>

  <th>
    Notes
  </th>
</tr>

  <td>
    "Resource Limit Exceeded"
  </td>

  <td>
    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 `[email protected]` to discuss an Enterprise wallet plan that fits your needs.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "The issuer \{\{issuer name}} is not supported"
  </td>

  <td>
    Use an OAuth provider from the list of [supported providers](https://docs.sui.io/concepts/cryptography/zklogin#openid-providers).
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "Bad jwt. The Token has expired on 2023-11-08T23:52:00Z."
  </td>

  <td>
    Ensure you're using a non-expired JWT.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    "Nonce TjpyZAr252rQ8dzOwoA1vioMTzY does not match computed nonce LAo4DvFaHZ88kREHZmRqgz8EBVw"
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    \-32602
  </td>

  <td>
    '\{"name":"InputValidationError","message":"JWT randomness 8641894711085230802105740842295470710772303705 must be 16 bytes"}'
  </td>

  <td>
    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`.
  </td>
</tr>

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

// 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":"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({{gasStationAccessKey}});

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

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