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.
Code | Message | Explanation |
---|---|---|
400 | Bad Request | Incorrect HTTP Request type (e.g., using GET instead of POST) or Invalid Characters |
401 | Unauthorized | This can happen when one or multiple security requirements are not met, such as incorrect Token Auth, IP not in the whitelist, invalid JWT, etc. |
403 | Forbidden | Endpoint Disabled (One reason could be a past due payment) |
403 | Forbidden - custom trace not found in allowed custom traces | Custom trace code not whitelisted. Submit a ticket here for approval. |
404 | Not Found | Incorrect URL or Incorrect method |
413 | Content Too Large | Body of the request is too large |
429 | Too Many Requests | The requests per second (RPS) of your requests are higher than your plan allows. Learn more here. |
500 | Internal Server Error | Submit a ticket for the support team to take a look at the errors. |
503 | Service Unavailable | Submit 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! 🚀