curl -X POST "https://api.blockdb.io/v1/evm/lineage/parents" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
}'
#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
CURL *curl = curl_easy_init();
if (!curl) return 1;
const char *token = getenv("BLOCKDB_API_KEY");
char auth_header[256];
snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
const char *payload = "{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, auth_header);
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/lineage/parents");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return res == CURLE_OK ? 0 : 1;
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));
var payload = new StringContent(
"{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/lineage/parents", payload);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
import os
import requests
response = requests.post(
"https://api.blockdb.io/v1/evm/lineage/parents",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'chain_id': 1,
'cursor': None,
'limit': 128,
'max_depth': 3,
'tracing_id': '0301000000000000000000000000000000000001'}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/lineage/parents", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/lineage/parents", payload)
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
// Handle response
}
{
"meta": {
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001"
},
"data": [
{
"dataset": "blockdb_evm.0103_logs_v1",
"_tracing_id": "0103000000000000000000000000000000000001",
"child_tracing_id": "0301000000000000000000000000000000000001",
"relationship": "source_log",
"depth": 1
},
{
"dataset": "blockdb_evm.0211_liquidity_pools_v1",
"_tracing_id": "0211000000000000000000000000000000000002",
"child_tracing_id": "0301000000000000000000000000000000000001",
"relationship": "pool_metadata",
"depth": 1
},
{
"dataset": "blockdb_evm.0102_transactions_v1",
"_tracing_id": "0102000000000000000000000000000000000003",
"child_tracing_id": "0103000000000000000000000000000000000001",
"relationship": "source_transaction",
"depth": 2
}
],
"cursor": "next_cursor",
"page_count": 3,
"truncation_reason": null
}
{
"error": {
"code": "BAD_REQUEST",
"http_status": 400,
"message": "The request contains invalid or missing parameters.",
"hint": "Validate all required parameters against the endpoint specification before retrying.",
"severity": "error",
"retryable": false,
"details": {
"invalid_parameters": [
{
"name": "chain_id",
"location": "query",
"reason": "missing",
"expected": "positive integer, e.g. 1"
},
{
"name": "from_timestamp",
"location": "query",
"reason": "invalid_format",
"expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
}
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/home"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"http_status": 401,
"message": "Invalid or missing API key.",
"hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
"severity": "error",
"retryable": false,
"details": {
"auth_scheme": "bearer",
"expected_header": "Authorization: Bearer <API_KEY>",
"provided_header": "Authorization: <REDACTED_OR_MISSING>",
"token_status": "invalid_or_missing",
"recommendation": "Regenerate the API key if you suspect it is expired or compromised."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
}
}
{
"error": {
"code": "FORBIDDEN",
"http_status": 403,
"message": "Your API key does not have permission to access this endpoint.",
"hint": "Upgrade your subscription tier or request additional access.",
"severity": "warning",
"retryable": false,
"details": {
"required_plan": "production",
"your_plan": null,
"contact": "support@blockdb.io",
"recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "NOT_FOUND",
"http_status": 404,
"message": "The requested resource does not exist.",
"hint": "Verify the API endpoint",
"severity": "warning",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"http_status": 413,
"message": "The requested response exceeds the maximum allowed size of 10 MB.",
"hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
"details": {
"max_allowed_bytes": 10485760,
"estimated_response_bytes": 15360000,
"recommended_actions": [
"Decrease the 'limit' parameter value",
"Shorten the block range or time window",
"Filter by fewer pools or exchanges"
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
}
}
{
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"http_status": 422,
"message": "chain_id=137 is not supported.",
"hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
"severity": "error",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"http_status": 429,
"message": "You have exceeded the allowed request rate.",
"hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
"details": {
"limit_rps": 1000, # configured rate limit
"current_estimated_rps": 73,
"retry_after_seconds": 2,
"limit_scope": "api_key",
"limit_window_seconds": 1
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"http_status": 500,
"message": "An unexpected server error occurred.",
"hint": "This error is not caused by your request. You may retry after a short delay.",
"severity": "critical",
"retryable": true,
"details": {
"incident_id": "INC-2025-11-11-123456",
"temporary_issue": true,
"expected_recovery_seconds": 5
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"http_status": 503,
"message": "The service is temporarily unable to handle the request.",
"hint": "The database connection pool is briefly saturated. Retry after a short delay.",
"severity": "warning",
"retryable": true,
"details": null,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
Lineage
Lineage Parents
Traverse upstream dependencies for any traced record.
POST
/
v1
/
evm
/
lineage
/
parents
curl -X POST "https://api.blockdb.io/v1/evm/lineage/parents" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
}'
#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
CURL *curl = curl_easy_init();
if (!curl) return 1;
const char *token = getenv("BLOCKDB_API_KEY");
char auth_header[256];
snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
const char *payload = "{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, auth_header);
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/lineage/parents");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return res == CURLE_OK ? 0 : 1;
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));
var payload = new StringContent(
"{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/lineage/parents", payload);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
import os
import requests
response = requests.post(
"https://api.blockdb.io/v1/evm/lineage/parents",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'chain_id': 1,
'cursor': None,
'limit': 128,
'max_depth': 3,
'tracing_id': '0301000000000000000000000000000000000001'}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/lineage/parents", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/lineage/parents", payload)
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
// Handle response
}
{
"meta": {
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001"
},
"data": [
{
"dataset": "blockdb_evm.0103_logs_v1",
"_tracing_id": "0103000000000000000000000000000000000001",
"child_tracing_id": "0301000000000000000000000000000000000001",
"relationship": "source_log",
"depth": 1
},
{
"dataset": "blockdb_evm.0211_liquidity_pools_v1",
"_tracing_id": "0211000000000000000000000000000000000002",
"child_tracing_id": "0301000000000000000000000000000000000001",
"relationship": "pool_metadata",
"depth": 1
},
{
"dataset": "blockdb_evm.0102_transactions_v1",
"_tracing_id": "0102000000000000000000000000000000000003",
"child_tracing_id": "0103000000000000000000000000000000000001",
"relationship": "source_transaction",
"depth": 2
}
],
"cursor": "next_cursor",
"page_count": 3,
"truncation_reason": null
}
{
"error": {
"code": "BAD_REQUEST",
"http_status": 400,
"message": "The request contains invalid or missing parameters.",
"hint": "Validate all required parameters against the endpoint specification before retrying.",
"severity": "error",
"retryable": false,
"details": {
"invalid_parameters": [
{
"name": "chain_id",
"location": "query",
"reason": "missing",
"expected": "positive integer, e.g. 1"
},
{
"name": "from_timestamp",
"location": "query",
"reason": "invalid_format",
"expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
}
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/home"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"http_status": 401,
"message": "Invalid or missing API key.",
"hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
"severity": "error",
"retryable": false,
"details": {
"auth_scheme": "bearer",
"expected_header": "Authorization: Bearer <API_KEY>",
"provided_header": "Authorization: <REDACTED_OR_MISSING>",
"token_status": "invalid_or_missing",
"recommendation": "Regenerate the API key if you suspect it is expired or compromised."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
}
}
{
"error": {
"code": "FORBIDDEN",
"http_status": 403,
"message": "Your API key does not have permission to access this endpoint.",
"hint": "Upgrade your subscription tier or request additional access.",
"severity": "warning",
"retryable": false,
"details": {
"required_plan": "production",
"your_plan": null,
"contact": "support@blockdb.io",
"recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "NOT_FOUND",
"http_status": 404,
"message": "The requested resource does not exist.",
"hint": "Verify the API endpoint",
"severity": "warning",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"http_status": 413,
"message": "The requested response exceeds the maximum allowed size of 10 MB.",
"hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
"details": {
"max_allowed_bytes": 10485760,
"estimated_response_bytes": 15360000,
"recommended_actions": [
"Decrease the 'limit' parameter value",
"Shorten the block range or time window",
"Filter by fewer pools or exchanges"
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
}
}
{
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"http_status": 422,
"message": "chain_id=137 is not supported.",
"hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
"severity": "error",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"http_status": 429,
"message": "You have exceeded the allowed request rate.",
"hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
"details": {
"limit_rps": 1000, # configured rate limit
"current_estimated_rps": 73,
"retry_after_seconds": 2,
"limit_scope": "api_key",
"limit_window_seconds": 1
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"http_status": 500,
"message": "An unexpected server error occurred.",
"hint": "This error is not caused by your request. You may retry after a short delay.",
"severity": "critical",
"retryable": true,
"details": {
"incident_id": "INC-2025-11-11-123456",
"temporary_issue": true,
"expected_recovery_seconds": 5
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"http_status": 503,
"message": "The service is temporarily unable to handle the request.",
"hint": "The database connection pool is briefly saturated. Retry after a short delay.",
"severity": "warning",
"retryable": true,
"details": null,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
Overview
Traverses the upstream dependency graph of the supplied record. Each node includes relationship metadata so you can follow the chain of derivations to a configurable depth.Parameters
Target EVM network.
Anchor record whose parents should be returned, provided as a hex string (no
0x prefix).Traversal Controls
Number of hops to follow.
1 returns direct parents, 2 includes grandparents, etc. Requests exceeding the configured maximum are truncated with a truncation_reason.When
true, each returned node is hydrated with its full record (the same payload the record endpoint returns). Only the nodes on the returned page are hydrated. Leave false to keep traversal responses small.Pagination Controls
Recommended default
250; maximum 1000 to stay under ~10 MB responses.Opaque pagination cursor returned from a prior call.
Response Fields
Meta
Echo of request metadata applied to the response.
EVM chain ID echoed from the request.
Tracing identifier for the record whose parents are returned.
Data
Each element represents a parent node that matches the requested depth and relationship filters.
Dataset namespace for the parent record.
Lineage identifier for the parent record (hex string, no
0x prefix). Feed this back into other lineage endpoints to continue traversal.Tracing identifier of the record one hop closer to the queried record that this node is a direct parent of. For
depth: 1 nodes this equals meta.tracing_id. Combine with relationship to rebuild the lineage tree edge by edge (this node is the <relationship> of child_tracing_id).How this node relates to its
child_tracing_id (e.g., source_log, pool_metadata, dependency).Hop count from the original record (
1 for direct parents).Full row for the node, in the same shape as the record endpoint’s
data.record. Present only when the request sets include_record: true; omitted otherwise.Envelope Fields
Pagination cursor for fetching additional parents.
Number of parent nodes returned in
data.Non-null when the server stopped traversal due to max depth, fan-out limits, or other safety guards.
Next Steps
- Fetch each parent’s full record via
/evm/lineage/record.
curl -X POST "https://api.blockdb.io/v1/evm/lineage/parents" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
}'
#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
CURL *curl = curl_easy_init();
if (!curl) return 1;
const char *token = getenv("BLOCKDB_API_KEY");
char auth_header[256];
snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
const char *payload = "{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, auth_header);
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/lineage/parents");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return res == CURLE_OK ? 0 : 1;
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));
var payload = new StringContent(
"{\"chain_id\":1,\"tracing_id\":\"0301000000000000000000000000000000000001\",\"max_depth\":3,\"cursor\":null,\"limit\":128}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/lineage/parents", payload);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
import os
import requests
response = requests.post(
"https://api.blockdb.io/v1/evm/lineage/parents",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'chain_id': 1,
'cursor': None,
'limit': 128,
'max_depth': 3,
'tracing_id': '0301000000000000000000000000000000000001'}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/lineage/parents", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001",
"max_depth": 3,
"cursor": null,
"limit": 128
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/lineage/parents", payload)
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
// Handle response
}
{
"meta": {
"chain_id": 1,
"tracing_id": "0301000000000000000000000000000000000001"
},
"data": [
{
"dataset": "blockdb_evm.0103_logs_v1",
"_tracing_id": "0103000000000000000000000000000000000001",
"child_tracing_id": "0301000000000000000000000000000000000001",
"relationship": "source_log",
"depth": 1
},
{
"dataset": "blockdb_evm.0211_liquidity_pools_v1",
"_tracing_id": "0211000000000000000000000000000000000002",
"child_tracing_id": "0301000000000000000000000000000000000001",
"relationship": "pool_metadata",
"depth": 1
},
{
"dataset": "blockdb_evm.0102_transactions_v1",
"_tracing_id": "0102000000000000000000000000000000000003",
"child_tracing_id": "0103000000000000000000000000000000000001",
"relationship": "source_transaction",
"depth": 2
}
],
"cursor": "next_cursor",
"page_count": 3,
"truncation_reason": null
}
{
"error": {
"code": "BAD_REQUEST",
"http_status": 400,
"message": "The request contains invalid or missing parameters.",
"hint": "Validate all required parameters against the endpoint specification before retrying.",
"severity": "error",
"retryable": false,
"details": {
"invalid_parameters": [
{
"name": "chain_id",
"location": "query",
"reason": "missing",
"expected": "positive integer, e.g. 1"
},
{
"name": "from_timestamp",
"location": "query",
"reason": "invalid_format",
"expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
}
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/home"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"http_status": 401,
"message": "Invalid or missing API key.",
"hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
"severity": "error",
"retryable": false,
"details": {
"auth_scheme": "bearer",
"expected_header": "Authorization: Bearer <API_KEY>",
"provided_header": "Authorization: <REDACTED_OR_MISSING>",
"token_status": "invalid_or_missing",
"recommendation": "Regenerate the API key if you suspect it is expired or compromised."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
}
}
{
"error": {
"code": "FORBIDDEN",
"http_status": 403,
"message": "Your API key does not have permission to access this endpoint.",
"hint": "Upgrade your subscription tier or request additional access.",
"severity": "warning",
"retryable": false,
"details": {
"required_plan": "production",
"your_plan": null,
"contact": "support@blockdb.io",
"recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "NOT_FOUND",
"http_status": 404,
"message": "The requested resource does not exist.",
"hint": "Verify the API endpoint",
"severity": "warning",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"http_status": 413,
"message": "The requested response exceeds the maximum allowed size of 10 MB.",
"hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
"details": {
"max_allowed_bytes": 10485760,
"estimated_response_bytes": 15360000,
"recommended_actions": [
"Decrease the 'limit' parameter value",
"Shorten the block range or time window",
"Filter by fewer pools or exchanges"
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
}
}
{
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"http_status": 422,
"message": "chain_id=137 is not supported.",
"hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
"severity": "error",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"http_status": 429,
"message": "You have exceeded the allowed request rate.",
"hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
"details": {
"limit_rps": 1000, # configured rate limit
"current_estimated_rps": 73,
"retry_after_seconds": 2,
"limit_scope": "api_key",
"limit_window_seconds": 1
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"http_status": 500,
"message": "An unexpected server error occurred.",
"hint": "This error is not caused by your request. You may retry after a short delay.",
"severity": "critical",
"retryable": true,
"details": {
"incident_id": "INC-2025-11-11-123456",
"temporary_issue": true,
"expected_recovery_seconds": 5
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"http_status": 503,
"message": "The service is temporarily unable to handle the request.",
"hint": "The database connection pool is briefly saturated. Retry after a short delay.",
"severity": "warning",
"retryable": true,
"details": null,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
Last modified on July 2, 2026
Was this page helpful?
⌘I