Skip to main content

Stacks Error Code Reference

Updated on
Jan 15, 2025

This document covers the error codes you might encounter while using a QuickNode Stacks endpoint. Understanding these codes helps you troubleshoot issues efficiently and build more reliable applications.

Error codes on your Stacks endpoint fall into two main categories:

  • QuickNode HTTP Status Codes: Standard web protocol errors returned by QuickNode's API infrastructure
  • Stacks-Specific Codes: Native blockchain errors returned by the Stacks network

For information about Stacks-specific error codes, visit the Stacks official documentation.

HTTP Error Codes

The table below lists the common HTTP errors you might encounter on a QuickNode Stacks endpoint and what they mean.

CodeMessageExplanation
400Bad RequestIncorrect HTTP Request type (e.g., using GET instead of POST) or Invalid Characters
401UnauthorizedThis can happen when one or multiple security requirements are not met, such as incorrect Token Auth, IP not in the whitelist, invalid JWT, etc.
403ForbiddenEndpoint Disabled (One reason could be a past due payment)
403Forbidden - custom trace not found in allowed custom tracesCustom trace code not whitelisted. Submit a ticket here for approval.
404Not FoundIncorrect URL or Incorrect method
413Content Too LargeBody of the request is too large
429Too Many RequestsThe requests per second (RPS) of your requests are higher than your plan allows. Learn more here.
500Internal Server ErrorSubmit a ticket for the support team to take a look at the errors.
503Service UnavailableSubmit a ticket for the support team to take a look at the errors.

HTTP Error Code Example

The code snippet below is an example of Error Code 429.

{
"jsonrpc": "2.0",
"error": {
"code": 429,
"message": "The requests per second (RPS) of your requests are higher than your plan allows."
},
"id": 1
}

If you're experiencing other error codes, please let us know by submitting a ticket. We're more than happy to assist! 🚀

Share this doc