Skip to content

Commit 4a8280f

Browse files
shaneauerbachcursoragentshane
authored
feat: Add support for warnings in API responses (#136)
This commit introduces warnings to API responses, allowing for non-fatal issues to be communicated. This includes updates to documentation and OpenAPI specifications for error-handling, activity, balances, and transactions endpoints. Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: shane <shane@dune.com>
1 parent 1620b1b commit 4a8280f

File tree

7 files changed

+554
-168
lines changed

7 files changed

+554
-168
lines changed

‎error-handling.mdx‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,44 @@ description: "How to handle errors when using Sim APIs"
55

66
This guide explains how to handle errors when using Sim APIs, including common error codes, troubleshooting steps, and code examples for proper error handling.
77

8+
## Errors vs. Warnings
9+
10+
Sim APIs distinguish between **errors** and **warnings**:
11+
12+
- **Errors** indicate that the request failed and could not be fulfilled. The API returns an error response with an HTTP 4xx or 5xx status code.
13+
- **Warnings** indicate non-fatal issues where the request was partially fulfilled. The API returns a successful HTTP 200 response with data, but includes a `warnings` array to inform you about issues that occurred.
14+
15+
### When Warnings Occur
16+
17+
Warnings are currently used when you request data for specific chains via the `chain_ids` parameter and some of those chains are not supported. For example:
18+
19+
- If you request `?chain_ids=1,9999,10` and chain 9999 is not supported, the API will return data for chains 1 and 10, plus a warning about chain 9999.
20+
21+
### Warning Response Format
22+
23+
When warnings are present, they appear in a `warnings` array within the successful (HTTP 200) response:
24+
25+
```json
26+
{
27+
"wallet_address": "0x37305b1cd40574e4c5ce33f8e8306be057fd7341",
28+
"balances": [...],
29+
"warnings": [
30+
{
31+
"code": "UNSUPPORTED_CHAIN_IDS",
32+
"message": "Some requested chain_ids are not supported. Balances are returned only for supported chains.",
33+
"chain_ids": [9999, 77777777777],
34+
"docs_url": "https://docs.sim.dune.com/evm/supported-chains"
35+
}
36+
]
37+
}
38+
```
39+
40+
Each warning includes:
41+
- `code`: A machine-readable warning code (e.g., `UNSUPPORTED_CHAIN_IDS`)
42+
- `message`: A human-readable description of the warning
43+
- `chain_ids`: The list of chain IDs that caused this warning (for chain-related warnings)
44+
- `docs_url`: A link to relevant documentation for more information
45+
846
## Error Response Format
947

1048
When an error occurs, Sim APIs return a JSON response with error information:
@@ -30,6 +68,58 @@ The error property can be either `"error"` or `"message"` depending on the type
3068
| 429 | Too many requests | Implement backoff strategies and consider upgrading your plan if you consistently hit limits |
3169
| 500 | Server-side error | Retry the request after a short delay; if persistent, contact support |
3270

71+
## Handling Warnings in Code
72+
73+
When processing API responses, check for the `warnings` array to be notified of non-fatal issues:
74+
75+
<Tabs>
76+
<Tab title="JavaScript">
77+
```javascript
78+
const response = await fetch('https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045?chain_ids=1,9999,10', {
79+
headers: {'X-Sim-Api-Key': 'YOUR_API_KEY'}
80+
});
81+
82+
const data = await response.json();
83+
84+
// Check for warnings
85+
if (data.warnings && data.warnings.length > 0) {
86+
data.warnings.forEach(warning => {
87+
if (warning.code === 'UNSUPPORTED_CHAIN_IDS') {
88+
console.warn(`Warning: Chains ${warning.chain_ids.join(', ')} are not supported.`);
89+
console.warn(`See: ${warning.docs_url}`);
90+
}
91+
});
92+
}
93+
94+
// Process the data that was successfully returned
95+
console.log(`Found ${data.balances.length} balances`);
96+
```
97+
</Tab>
98+
<Tab title="Python">
99+
```python
100+
import requests
101+
102+
response = requests.get(
103+
'https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
104+
headers={'X-Sim-Api-Key': 'YOUR_API_KEY'},
105+
params={'chain_ids': '1,9999,10'}
106+
)
107+
108+
data = response.json()
109+
110+
# Check for warnings
111+
if 'warnings' in data and len(data['warnings']) > 0:
112+
for warning in data['warnings']:
113+
if warning['code'] == 'UNSUPPORTED_CHAIN_IDS':
114+
print(f"Warning: Chains {warning['chain_ids']} are not supported.")
115+
print(f"See: {warning['docs_url']}")
116+
117+
# Process the data that was successfully returned
118+
print(f"Found {len(data['balances'])} balances")
119+
```
120+
</Tab>
121+
</Tabs>
122+
33123
## Handling Errors in Code
34124

35125
Here are examples of how to properly handle errors in different programming languages:

‎evm/activity.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,54 @@ Sim APIs are designed to automatically detect and handle blockchain re-organizat
3838
We detect any potentially broken parent-child block relationships as soon as they arise and update our internal state to match the onchain state, typically within a few hundred milliseconds.
3939
This re-org handling is an automatic, non-configurable feature designed to provide the most reliable data.
4040

41+
## Warnings
42+
43+
When requesting activity for specific chains using the `chain_ids` parameter, the API may return warnings if some requested chain IDs are not supported. Unlike errors, warnings indicate non-fatal issues where the request can still be partially fulfilled.
44+
45+
When unsupported chain IDs are included in your request, the API will:
46+
- Return activity for all supported chains you requested
47+
- Include a `warnings` array in the response with details about the unsupported chains
48+
49+
### Example: Request with Unsupported Chain IDs
50+
51+
If you request `?chain_ids=1,9999,10`, the API returns activity for chains 1 and 10 (supported), and includes a warning about chain 9999 (unsupported):
52+
53+
```json
54+
{
55+
"activity": [
56+
{
57+
"chain_id": 1,
58+
"block_number": 18500000,
59+
"block_time": "2025-02-20T13:52:29+00:00",
60+
"tx_hash": "0x184544c8d67a0cbed0a3f04abe5f958b96635e8c743c070f70e24b1c06cd1aa6",
61+
"type": "receive",
62+
"asset_type": "erc20",
63+
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
64+
"from": "0xd152f549545093347a162dce210e7293f1452150",
65+
"value": "1000000",
66+
"value_usd": 1.0,
67+
"token_metadata": {
68+
"symbol": "USDC",
69+
"decimals": 6,
70+
"price_usd": 1.0
71+
}
72+
}
73+
],
74+
"warnings": [
75+
{
76+
"code": "UNSUPPORTED_CHAIN_IDS",
77+
"message": "Some requested chain_ids are not supported. Activity is returned only for supported chains.",
78+
"chain_ids": [9999],
79+
"docs_url": "https://docs.sim.dune.com/evm/supported-chains"
80+
}
81+
]
82+
}
83+
```
84+
85+
<Tip>
86+
Check the [Supported Chains](/evm/supported-chains) page to see which chains are currently supported for the Activity endpoint.
87+
</Tip>
88+
4189
## Token Filtering
4290

4391
We include all the data needed for custom filtering in the responses, allowing you to implement your own filtering logic. For a detailed explanation of our approach, see our [Token Filtering](/token-filtering) guide.

‎evm/balances.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,58 @@ When set, each balance includes a `historical_prices` array with one entry per o
7373
The maximum number of historical price offsets is 3. If more than 3 are provided, the API returns an error.
7474
</Warning>
7575

76+
## Warnings
77+
78+
When requesting balances for specific chains using the `chain_ids` parameter, the API may return warnings if some requested chain IDs are not supported. Unlike errors, warnings indicate non-fatal issues where the request can still be partially fulfilled.
79+
80+
When unsupported chain IDs are included in your request, the API will:
81+
- Return balances for all supported chains you requested
82+
- Include a `warnings` array in the response with details about the unsupported chains
83+
84+
### Example: Request with Unsupported Chain IDs
85+
86+
If you request `?chain_ids=1,9999,10,77777777777`, the API returns balances for chains 1 and 10 (supported), and includes a warning about chains 9999 and 77777777777 (unsupported):
87+
88+
```json
89+
{
90+
"wallet_address": "0x37305b1cd40574e4c5ce33f8e8306be057fd7341",
91+
"balances": [
92+
{
93+
"chain": "ethereum",
94+
"chain_id": 1,
95+
"address": "native",
96+
"amount": "1000000000000000000",
97+
"symbol": "ETH",
98+
"decimals": 18,
99+
"price_usd": 3896.8315,
100+
"value_usd": 3896.8315
101+
},
102+
{
103+
"chain": "optimism",
104+
"chain_id": 10,
105+
"address": "native",
106+
"amount": "500000000000000000",
107+
"symbol": "ETH",
108+
"decimals": 18,
109+
"price_usd": 3896.8315,
110+
"value_usd": 1948.41575
111+
}
112+
],
113+
"warnings": [
114+
{
115+
"code": "UNSUPPORTED_CHAIN_IDS",
116+
"message": "Some requested chain_ids are not supported. Balances are returned only for supported chains.",
117+
"chain_ids": [9999, 77777777777],
118+
"docs_url": "https://docs.sim.dune.com/evm/supported-chains"
119+
}
120+
]
121+
}
122+
```
123+
124+
<Tip>
125+
Check the [Supported Chains](/evm/supported-chains) page to see which chains are currently supported for the Balances endpoint.
126+
</Tip>
127+
76128
## Pagination
77129

78130
This endpoint is using cursor based pagination. You can use the `limit` query parameter to define the maximum page size.

‎evm/openapi/activity.json‎

Lines changed: 98 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -83,28 +83,66 @@
8383
"schema": {
8484
"$ref": "#/components/schemas/ActivityResponse"
8585
},
86-
"example": {
87-
"activity": [
88-
{
89-
"chain_id": 8453,
90-
"block_number": 26635101,
91-
"block_time": "2025-02-20T13:52:29+00:00",
92-
"tx_hash": "0x184544c8d67a0cbed0a3f04abe5f958b96635e8c743c070f70e24b1c06cd1aa6",
93-
"type": "receive",
94-
"asset_type": "erc20",
95-
"token_address": "0xf92e740ad181b13a484a886ed16aa6d32d71b19a",
96-
"from": "0xd152f549545093347a162dce210e7293f1452150",
97-
"value": "123069652500000000000",
98-
"value_usd": 0.14017463965013963,
99-
"token_metadata": {
100-
"symbol": "ENT",
101-
"decimals": 18,
102-
"price_usd": 0.001138986230989314,
103-
"pool_size": 5.2274054439382835
104-
}
86+
"examples": {
87+
"success": {
88+
"summary": "Successful response",
89+
"value": {
90+
"activity": [
91+
{
92+
"chain_id": 8453,
93+
"block_number": 26635101,
94+
"block_time": "2025-02-20T13:52:29+00:00",
95+
"tx_hash": "0x184544c8d67a0cbed0a3f04abe5f958b96635e8c743c070f70e24b1c06cd1aa6",
96+
"type": "receive",
97+
"asset_type": "erc20",
98+
"token_address": "0xf92e740ad181b13a484a886ed16aa6d32d71b19a",
99+
"from": "0xd152f549545093347a162dce210e7293f1452150",
100+
"value": "123069652500000000000",
101+
"value_usd": 0.14017463965013963,
102+
"token_metadata": {
103+
"symbol": "ENT",
104+
"decimals": 18,
105+
"price_usd": 0.001138986230989314,
106+
"pool_size": 5.2274054439382835
107+
}
108+
}
109+
],
110+
"next_offset": "KgAAAAAAAAAweDQ4ZDAwNGE2YzE3NWRiMzMxZTk5YmVhZjY0NDIzYjMwOTgzNTdhZTdAVxVC-y0GAAUhAAAAAAAA6XCRAQAAAAAAAAAAAAAAAD0AAAAAAAAAAAAAAAAAAAA"
111+
}
112+
},
113+
"with_warnings": {
114+
"summary": "Response with unsupported chain IDs warning",
115+
"value": {
116+
"activity": [
117+
{
118+
"chain_id": 1,
119+
"block_number": 18500000,
120+
"block_time": "2025-02-20T13:52:29+00:00",
121+
"tx_hash": "0x184544c8d67a0cbed0a3f04abe5f958b96635e8c743c070f70e24b1c06cd1aa6",
122+
"type": "receive",
123+
"asset_type": "erc20",
124+
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
125+
"from": "0xd152f549545093347a162dce210e7293f1452150",
126+
"value": "1000000",
127+
"value_usd": 1.0,
128+
"token_metadata": {
129+
"symbol": "USDC",
130+
"decimals": 6,
131+
"price_usd": 1.0
132+
}
133+
}
134+
],
135+
"warnings": [
136+
{
137+
"code": "UNSUPPORTED_CHAIN_IDS",
138+
"message": "Some requested chain_ids are not supported. Activity is returned only for supported chains.",
139+
"chain_ids": [9999, 77777777777],
140+
"docs_url": "https://docs.sim.dune.com/evm/supported-chains"
141+
}
142+
],
143+
"next_offset": "KgAAAAAAAAAweDQ4ZDAwNGE2YzE3NWRiMzMxZTk5YmVhZjY0NDIzYjMwOTgzNTdhZTdAVxVC-y0GAAUhAAAAAAAA6XCRAQAAAAAAAAAAAAAAAD0AAAAAAAAAAAAAAAAAAAA"
105144
}
106-
],
107-
"next_offset": "KgAAAAAAAAAweDQ4ZDAwNGE2YzE3NWRiMzMxZTk5YmVhZjY0NDIzYjMwOTgzNTdhZTdAVxVC-y0GAAUhAAAAAAAA6XCRAQAAAAAAAAAAAAAAAD0AAAAAAAAAAAAAAAAAAAA"
145+
}
108146
}
109147
}
110148
}
@@ -324,6 +362,38 @@
324362
}
325363
}
326364
},
365+
"Warning": {
366+
"type": "object",
367+
"required": [
368+
"code",
369+
"message"
370+
],
371+
"properties": {
372+
"code": {
373+
"type": "string",
374+
"description": "Warning code identifier (e.g., 'UNSUPPORTED_CHAIN_IDS')",
375+
"example": "UNSUPPORTED_CHAIN_IDS"
376+
},
377+
"message": {
378+
"type": "string",
379+
"description": "Human-readable warning message",
380+
"example": "Some requested chain_ids are not supported. Activity is returned only for supported chains."
381+
},
382+
"chain_ids": {
383+
"type": "array",
384+
"items": {
385+
"type": "integer",
386+
"format": "int64"
387+
},
388+
"description": "List of chain IDs that triggered this warning (for chain-related warnings)"
389+
},
390+
"docs_url": {
391+
"type": "string",
392+
"description": "URL to documentation with more information about the warning",
393+
"example": "https://docs.sim.dune.com/evm/supported-chains"
394+
}
395+
}
396+
},
327397
"ActivityResponse": {
328398
"type": "object",
329399
"required": [
@@ -337,6 +407,13 @@
337407
},
338408
"description": "Array of activity items"
339409
},
410+
"warnings": {
411+
"type": "array",
412+
"items": {
413+
"$ref": "#/components/schemas/Warning"
414+
},
415+
"description": "Array of warnings that occurred during request processing. Warnings indicate non-fatal issues (e.g., unsupported chain IDs) where the request can still be partially fulfilled."
416+
},
340417
"next_offset": {
341418
"type": "string",
342419
"description": "Pagination cursor for the next page of results"

0 commit comments

Comments
 (0)