Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.
Zerion API uses standard HTTP status codes and returns structured error responses. This page covers what to expect and how to handle errors gracefully.
Error response format
All errors return a JSON object with an errors array:
{ "errors": [ { "title": "Short error description", "detail": "A longer explanation of what went wrong" } ]}
HTTP status codes
Status
Meaning
When it happens
200
Success
Request completed successfully
202
Accepted
NFT endpoints only: the wallet’s NFTs are still being indexed. Retry with backoff until you get 200
The requested resource doesn’t exist (single-resource endpoints only)
422
Unprocessable Entity
The request cannot be served, and retrying will not change that
429
Too Many Requests
Rate limit exceeded
500
Server Error
Unexpected error on Zerion’s side. Safe to retry with backoff
503
Service Unavailable
Data is still being prepared. Retry after the delay in the Retry-After header
400 - Bad Request
Returned when query parameters are malformed or invalid. Check the detail field for specifics.
{ "errors": [ { "title": "Malformed parameter was sent", "detail": "chain {invalidchain} is not supported" } ]}
Common causes:
Invalid filter[chain_ids] value (e.g., a chain ID that doesn’t exist)
page[size] outside the allowed range (the maximum varies by endpoint)
Missing required parameters (e.g., filter[references] on the NFTs endpoint)
Malformed filter[min_mined_at] timestamp (must be exactly 13 digits, in milliseconds)
An address Zerion doesn’t track (see below)
Untracked addresses
The PnL, transactions and NFT endpoints only accept addresses that behave like user wallets, and reject anything else before doing any work:
{ "errors": [ { "title": "Malformed parameter was sent", "detail": "address 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 is not trackable" } ]}
Rejected: contracts that aren’t recognized smart-contract wallets (token contracts, routers, vaults), burn and reserved addresses, and high-volume addresses such as exchange hot wallets and mining pools. Smart-contract wallets are fine: Safe, Coinbase Smart Wallet, ERC-4337 accounts and EIP-7702 delegated EOAs all work.Recognition works by wallet implementation, so a newly deployed Safe is tracked immediately with no setup. Trackability is decided per address, not per chain. If you need a specific address, or a wallet implementation Zerion doesn’t recognize yet, contact support.
401 - Unauthorized
Returned when the API key is missing, invalid, or incorrectly encoded.
{ "errors": [ { "title": "Unauthorized Error", "detail": "The API key is invalid, please, make sure that you are using a valid key" } ]}
Common causes:
Missing Authorization header
API key not Base64-encoded correctly. Remember to append a colon: base64("your_key:")
Expired or revoked API key
Test your encoding: echo -n "your_api_key:" | base64 should produce the value you pass after Basic .
404 - Not Found
Returned on single-resource endpoints when the ID doesn’t match any record.
{ "errors": [ { "title": "Requested fungible was not found", "detail": "You have requested fungible which does not exist" } ]}
This only applies to endpoints like /v1/fungibles/{fungible_id} or /v1/nfts/{nft_id}. List endpoints return an empty data array instead of a 404.
422 - Unprocessable Entity
Returned when a request cannot be served and retrying will not change that. Unlike a 503, it carries no Retry-After header.
{ "errors": [ { "title": "This request is not supported", "detail": "This request cannot be processed, and retrying will not help. Please contact support if you need it enabled." } ]}
The PnL endpoints (/v1/wallets/{address}/pnl and /v1/wallet-sets/pnl) return it for wallets with more than 1 million actions, which are too large for PnL to be calculated. The limit is counted per address, so a wallet set fails if any one of its addresses is over it.Don’t retry, and don’t cache the result against the address: the same address can return a different status later.
429 - Too Many Requests
Returned when you exceed your plan’s rate limit.
{ "errors": [ { "title": "Too many requests", "detail": "Your request had been throttled" } ]}
Implement exponential backoff when retrying. For header details and retry guidance, see Rate limits. If you’re hitting limits consistently, upgrade your plan in the Dashboard.
500 - Server Error
Returned when something unexpected goes wrong on Zerion’s side.
These errors are safe to retry. Use exponential backoff (e.g., 1s, 2s, 4s) and cap your retries. If the error persists, reach out to support.
503 - Service Unavailable
Returned when the data you asked for is still being prepared. The PnL, wallet positions and fungible chart endpoints compute a wallet’s state on the first request, and answer with a 503 while that runs.
{ "errors": [ { "title": "Service is temporarily unavailable", "detail": "Please, retry later (check the Retry-After header)" } ]}
This always includes a Retry-After header, typically 10 seconds. Wait for it rather than retrying immediately, and cap your attempts.
Best practices
Retry on 429, 500 and 503. Do not retry 400, 401 or 422. These return the same result however many times you send them.
Respect Retry-After. On a 503 it tells you how long the data needs; retrying sooner burns your rate limit.
Use exponential backoff. When retrying, increase the delay between attempts exponentially (e.g., 1s, 2s, 4s) to avoid overwhelming the API.
Validate parameters before sending. Check that page[size] is within the endpoint’s allowed range, timestamps are 13-digit milliseconds, and chain IDs match the supported chains. This avoids unnecessary 400 errors.
Use webhooks instead of polling. If you need to monitor wallet activity, use transaction subscriptions instead of polling. This reduces API usage and gives you faster notifications.
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Zerion API","description":"Zerion is an Ethereum and Solana wallet and developer platform focused on making blockchain data easy to use.","colors":{"primary":"#2461ED","light":"#2461ED","dark":"#2461ED"},"logo":{"light":"https://mintcdn.com/zerion-f99485ad/7LRY3a3Ldx_ROK8O/logo/light.svg?fit=max\u0026auto=format\u0026n=7LRY3a3Ldx_ROK8O\u0026q=85\u0026s=f451fe390bc92095f03123a8f7d40a7d","dark":"https://mintcdn.com/zerion-f99485ad/7LRY3a3Ldx_ROK8O/logo/dark.svg?fit=max\u0026auto=format\u0026n=7LRY3a3Ldx_ROK8O\u0026q=85\u0026s=4062b6f0d31d9101cb18ec6912f5260c"},"favicon":"https://mintcdn.com/zerion-f99485ad/CtpXHzWVHRggjdYr/images/favicon.png?fit=max\u0026auto=format\u0026n=CtpXHzWVHRggjdYr\u0026q=85\u0026s=ab9d008382caaa72b969c16793e48ba4","api":{"playground":{"display":"interactive"},"examples":{"defaults":"required","languages":["curl","python","javascript","go"],"prefill":true}},"navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://dashboard.zerion.io"}},"footer":{"socials":{"x":"https://x.com/zerion","website":"https://zerion.io","linkedin":"https://www.linkedin.com/company/zeriontech"}},"fonts":{"heading":{"family":"Aeonik Pro","weight":700,"source":"fonts/AeonikPro-VF.woff2","format":"woff2"},"body":{"family":"Aeonik Pro","weight":400,"source":"fonts/AeonikPro-VF.woff2","format":"woff2"}},"integrations":{"ga4":{"measurementId":"G-KKSYM575R1"},"mixpanel":{"projectToken":"18a91a6fe2bdf70794ceb76c03433f19","region":"eu"},"posthog":{"apiKey":"phc_KpX0ph71XObDhlXXMKoAzXMtXYiNMMtDhuA8GvvudZI","apiHost":"https://eu.i.posthog.com"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"zerion-f99485ad","hasAudioNarration":false,"actualSubdomain":"zerion-f99485ad","customDomains":["developers.zerion.io"],"gitSource":{"type":"github","owner":"zeriontech","repo":"mintlify-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6b0067ac644638788944f025","clientVersion":"0.0.4248","searchFilterCounts":[{"language":"default","tag":"API Reference","count":41},{"language":"default","tag":"REST API","count":41},{"language":"default","tag":"Home","count":26},{"language":"default","tag":"subscriptions to transactions","count":14},{"language":"default","tag":"Get started","count":9},{"language":"default","tag":"Core concepts","count":9},{"language":"default","tag":"Recipes","count":9},{"language":"default","tag":"Guides","count":9},{"language":"default","tag":"Migrating to Zerion API","count":8},{"language":"default","tag":"wallets","count":8}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"global.css","href":"/_mintlify/custom/zerion-f99485ad/93bd2d8b1c0bdf0e/global.css"},{"filePath":"api-reference.css","content":".method-pill,.method-nav-pill>span{--m: #16a34a;color:var(--m)!important;background:color-mix(in srgb, var(--m) 12%, transparent)!important}:is(.method-pill,.method-nav-pill>span):is([class*=\"blue\"]){--m: #2461ed}:is(.method-pill,.method-nav-pill>span):is([class*=\"orange\"],[class*=\"yellow\"],[class*=\"amber\"]){--m: #ea580c}:is(.method-pill,.method-nav-pill>span):is([class*=\"red\"]){--m: #ef4444}:is(.method-pill,.method-nav-pill>span):is([class*=\"purple\"],[class*=\"violet\"]){--m: #8b5cf6}.dark :is(.method-pill,.method-nav-pill>span){--m: #4ade80}.dark :is(.method-pill,.method-nav-pill>span):is([class*=\"blue\"]){--m: #6b9bff}.dark :is(.method-pill,.method-nav-pill>span):is([class*=\"orange\"],[class*=\"yellow\"],[class*=\"amber\"]){--m: #fb923c}.dark :is(.method-pill,.method-nav-pill>span):is([class*=\"red\"]){--m: #f87171}.method-nav-pill{width:2.5rem!important}.method-nav-pill>span{min-width:2.25rem;padding:0.125rem 0!important;text-align:center;font-size:0.5625rem!important;letter-spacing:0.04em;border-radius:0.375rem!important}#navigation-items button[aria-expanded]>div:first-child>span{display:inline-block}#navigation-items button[aria-expanded]>div:first-child>span::first-letter{text-transform:uppercase}.method-pill{padding:0.125rem 0.5rem!important;font-size:0.75rem!important;letter-spacing:0.04em}.method-pill+div [class*=\"2AB673\"]{color:#2461ed!important;background:rgba(36, 97, 237, 0.07)!important;border:1px dashed rgba(36, 97, 237, 0.35)!important;padding:0 0.3rem!important}.dark .method-pill+div [class*=\"2AB673\"]{color:#8fb3ff!important;background:rgba(107, 155, 255, 0.1)!important;border-color:rgba(107, 155, 255, 0.35)!important}.tryit-button{border-radius:0.75rem!important;box-shadow:0 1px 2px rgba(36, 97, 237, 0.25), inset 0 1px 0 rgba(255, 255, 255, 0.15);transition:background-color 0.15s ease, transform 0.15s ease}.tryit-button:hover{opacity:1!important;background:#1d4fd0!important}.tryit-button:active{transform:translateY(1px)}.api-section-heading-title{font-size:0.75rem!important;font-weight:600!important;text-transform:uppercase;letter-spacing:0.06em;color:#71717a!important}.dark .api-section-heading-title{color:#a1a1aa!important}.primitive-param-field>div,.expandable-content .primitive-param-field>div{padding-top:1.25rem!important;padding-bottom:1.25rem!important}[data-component-part=\"field-name\"]{color:#0a0a0a!important;font-weight:600!important}.dark [data-component-part=\"field-name\"]{color:#fff!important}[data-component-part=\"field-info-pill\"]{padding:0.0625rem 0.45rem!important;border-radius:0.375rem!important;color:#52525b!important;background:#f4f4f5!important;font-weight:500!important}.dark [data-component-part=\"field-info-pill\"]{color:#d4d4d8!important;background:rgba(255, 255, 255, 0.06)!important}[data-component-part=\"field-required-pill\"]{padding:0.0625rem 0!important;background:none!important;color:#ea580c!important;font-weight:600!important}.dark [data-component-part=\"field-required-pill\"]{color:#fb923c!important}[data-component-part=\"expandable-button\"]{border-radius:999px!important;transition:background-color 0.15s ease, border-color 0.15s ease}[data-component-part=\"expandable-button\"]:hover{border-color:rgba(36, 97, 237, 0.35)!important}[data-component-part=\"expandable-content\"]{border-radius:0.875rem!important}#content-side-layout [data-component-part=\"code-block-root\"],#content-side-layout .code-block{border-radius:1rem!important;border-color:#ececef!important;box-shadow:0 1px 2px rgba(10, 10, 10, 0.04), 0 8px 24px -12px rgba(10, 10, 10, 0.08)}.dark #content-side-layout [data-component-part=\"code-block-root\"],.dark #content-side-layout .code-block{border-color:rgba(255, 255, 255, 0.08)!important;box-shadow:none}[data-status]{--s: #16a34a}[data-status^=\"3\"]{--s: #2461ed}[data-status^=\"4\"]{--s: #ea580c}[data-status^=\"5\"]{--s: #ef4444}.dark [data-status]{--s: #4ade80}.dark [data-status^=\"3\"]{--s: #6b9bff}.dark [data-status^=\"4\"]{--s: #fb923c}.dark [data-status^=\"5\"]{--s: #f87171}[data-component-part=\"code-group-tab-bar\"] button[data-status]>div:first-child{gap:0.375rem}[data-component-part=\"code-group-tab-bar\"] button[data-status]>div:first-child::before{content:\"\";width:0.375rem;height:0.375rem;border-radius:50%;background:var(--s)}[data-component-part=\"code-group-tab-bar\"] button[data-status][data-state=\"active\"]{color:var(--s)!important}[data-component-part=\"code-group-tab-bar\"] button[data-status][data-state=\"active\"]>div:last-child{background:var(--s)!important}@media (prefers-reduced-motion: reduce){.tryit-button,[data-component-part=\"expandable-button\"]{transition:none}}@media (min-width: 1280px){body:has(.method-pill) #toc-fallback{display:none!important}html body:has(.method-pill):has(#toc-fallback) #page-context-menu.ml-auto{display:flex!important}}"},{"filePath":"changelog.css","content":"[data-tag]{--t: #71717a}[data-tag=\"feature\"]{--t: #16a34a}[data-tag=\"improvement\"]{--t: #2461ed}[data-tag=\"change\"]{--t: #8b5cf6}[data-tag=\"fix\"]{--t: #ea580c}[data-tag=\"breaking\"]{--t: #ef4444}[data-tag=\"deprecation\"]{--t: #ca8a04}.dark [data-tag=\"docs\"]{--t: #a1a1aa}.dark [data-tag=\"improvement\"]{--t: #6b9bff}.dark [data-tag=\"change\"]{--t: #a78bfa}.update-container{padding-top:2.25rem!important;padding-bottom:2.25rem!important}.update-container [data-component-part=\"update-label\"]{padding:0!important;background:none!important;color:#0a0a0a!important;font-size:0.9375rem!important;font-weight:600!important;letter-spacing:-0.01em;cursor:pointer}.dark .update-container [data-component-part=\"update-label\"]{color:#fff!important}.update-container [data-component-part=\"update-description\"]{margin-top:0.4rem!important;padding:0!important;color:#71717a!important;font-size:0.8125rem!important;line-height:1.4}.dark .update-container [data-component-part=\"update-description\"]{color:#a1a1aa!important}.update-container [data-component-part=\"update-tag-list\"]{order:3;margin-top:0.75rem!important;padding:0!important;gap:0.375rem!important}.update-container [data-component-part=\"update-tag\"],#changelog-filters-content button{display:inline-flex!important;align-items:center;gap:0.375rem;border-radius:999px!important;font-weight:500!important;line-height:1.4}.update-container [data-component-part=\"update-tag\"]{padding:0.125rem 0.55rem!important;font-size:0.75rem!important;color:var(--t)!important;background:color-mix(in srgb, var(--t) 10%, transparent)}.update-container [data-component-part=\"update-tag\"]::before,#changelog-filters-content button::before{content:\"\";width:0.375rem;height:0.375rem;border-radius:50%;background:var(--t);flex-shrink:0}#changelog-filters-content button{padding:0.25rem 0.75rem!important;font-size:0.8125rem!important;color:#3f3f46!important;background:#fff!important;border:1px solid #e4e4e7;transition:border-color 0.15s ease, background-color 0.15s ease, color 0.15s ease}#changelog-filters-content button:hover{border-color:color-mix(in srgb, var(--t) 45%, transparent)}#changelog-filters-content button.bg-primary{color:var(--t)!important;background:color-mix(in srgb, var(--t) 10%, transparent)!important;border-color:color-mix(in srgb, var(--t) 45%, transparent)}.dark #changelog-filters-content button{color:#d4d4d8!important;background:transparent!important;border-color:rgba(255, 255, 255, 0.1)}.dark #changelog-filters-content button.bg-primary{color:var(--t)!important;background:color-mix(in srgb, var(--t) 14%, transparent)!important}html[data-changelog] #toc-fallback .toc-actions{top:calc(9.5rem + var(--cl-filters-h, 9rem) + 1rem)!important;padding-top:1rem!important;border-top:1px solid #ececef!important}.dark html[data-changelog] #toc-fallback .toc-actions,html.dark[data-changelog] #toc-fallback .toc-actions{border-top-color:rgba(255, 255, 255, 0.08)!important}.update-container [data-component-part=\"update-content\"]>h2:first-child{margin-top:0!important;font-size:1.375rem;line-height:1.35;letter-spacing:-0.02em}.update-container.cl-latest [data-component-part=\"update-tag-list\"]::after{content:\"Latest\";padding:0.0625rem 0.5rem;border-radius:999px;font-size:0.6875rem;font-weight:600;letter-spacing:0.02em;color:#fff;background:#2461ed}[data-component-part=\"update-content\"] .cl-endpoints-label{margin-bottom:0.5rem!important;font-size:0.75rem;text-transform:uppercase;letter-spacing:0.06em;color:#71717a}.dark [data-component-part=\"update-content\"] .cl-endpoints-label{color:#a1a1aa}[data-component-part=\"update-content\"] .cl-endpoints-label strong{font-weight:600;color:inherit}#content [data-component-part=\"update-content\"] ul.cl-endpoints{display:flex;flex-direction:column;gap:0.375rem;margin:0 0 1.25rem!important;padding:0!important;list-style:none!important}#content [data-component-part=\"update-content\"] ul.cl-endpoints>li{margin:0!important;padding:0!important}#content [data-component-part=\"update-content\"] ul.cl-endpoints>li::marker,#content [data-component-part=\"update-content\"] ul.cl-endpoints>li::before{content:none!important;display:none!important}#content [data-component-part=\"update-content\"] .cl-endpoint>code{display:inline-flex!important;align-items:center;gap:0.625rem;padding:0.3rem 0.75rem 0.3rem 0.3rem!important;border-radius:0.625rem!important;border:1px solid #ececef!important;background:#fafafa!important;color:#27272a!important;-webkit-text-fill-color:currentColor;font-size:0.8125rem!important}.dark #content [data-component-part=\"update-content\"] .cl-endpoint>code{border-color:rgba(255, 255, 255, 0.08)!important;background:rgba(255, 255, 255, 0.03)!important;color:#e4e4e7!important;-webkit-text-fill-color:currentColor}.cl-method{--m: #16a34a;min-width:3.25rem;padding:0.0625rem 0.4rem;border-radius:0.375rem;text-align:center;font-size:0.6875rem;font-weight:700;letter-spacing:0.02em;color:var(--m);-webkit-text-fill-color:var(--m);background:color-mix(in srgb, var(--m) 12%, transparent)}.cl-method[data-method=\"post\"]{--m: #2461ed}.cl-method[data-method=\"put\"],.cl-method[data-method=\"patch\"]{--m: #ea580c}.cl-method[data-method=\"delete\"]{--m: #ef4444}.dark .cl-method[data-method=\"post\"]{--m: #6b9bff}@media (min-width: 1024px){.update-container{gap:2.5rem!important}.update-container>div:last-child{position:relative;padding-left:2.5rem!important;padding-bottom:0.25rem;margin-top:-2.25rem;margin-bottom:-2.25rem;padding-top:2.25rem;overflow:visible!important;border-left:1px solid #ececef}.dark .update-container>div:last-child{border-left-color:rgba(255, 255, 255, 0.08)}.update-container>div:last-child>[data-component-part=\"update-content\"]{padding-bottom:2.25rem;overflow:hidden}.update-container>div:last-child::before{content:\"\";position:absolute;left:-0.375rem;top:calc(2.25rem + 0.55rem);width:0.75rem;height:0.75rem;border-radius:50%;background:#fff;border:2px solid #d4d4d8;transition:border-color 0.2s ease, box-shadow 0.2s ease}.dark .update-container>div:last-child::before{background:#0b0b0c;border-color:#52525b}.update-container:hover>div:last-child::before,.update-container.cl-latest>div:last-child::before{border-color:#2461ed;box-shadow:0 0 0 4px rgba(36, 97, 237, 0.12)}.update-container.cl-latest>div:last-child::before{background:#2461ed}}@media (max-width: 1023px){.update-container+.update-container{border-top:1px solid #ececef}.dark .update-container+.update-container{border-top-color:rgba(255, 255, 255, 0.08)}.update-container>div:first-child{flex-direction:row!important;flex-wrap:wrap;align-items:center!important;gap:0.5rem 0.75rem}.update-container [data-component-part=\"update-tag-list\"],.update-container [data-component-part=\"update-description\"]{margin-top:0!important}.update-container [data-component-part=\"update-description\"]{display:none}}@media (prefers-reduced-motion: reduce){.update-container>div:last-child::before,#changelog-filters-content button{transition:none}}html[data-changelog] #content-side-layout{pointer-events:none}html[data-changelog] #changelog-filters{pointer-events:auto}#changelog-filters-content button:not([data-tag])::before,.update-container [data-component-part=\"update-tag\"]:not([data-tag])::before{opacity:0}[data-component-part=\"update-content\"] :is(h2,h3)>div.absolute:has(>a[aria-label=\"Navigate to header\"]){display:none}"},{"filePath":"migrate.css","content":".mg-card{margin:1rem 0 1.5rem;border:1px solid #ececef;border-radius:1.125rem;overflow:hidden;background:#fff}.dark .mg-card{border-color:rgba(255, 255, 255, 0.08);background:transparent}.mg-band{display:flex;align-items:center;gap:1rem;padding:1.25rem 1.5rem;background:radial-gradient(1px 1px at 1px 1px, rgba(10, 10, 10, 0.07) 1px, transparent 0) 0 0 / 16px 16px,\n linear-gradient(90deg, #fafafb 0%, #eef2fb 100%);border-bottom:1px solid #f0f0f2}.dark .mg-band{background:radial-gradient(1px 1px at 1px 1px, rgba(255, 255, 255, 0.06) 1px, transparent 0) 0 0 / 16px 16px,\n linear-gradient(90deg, #0d0f16 0%, #0d1530 100%);border-bottom-color:rgba(255, 255, 255, 0.06)}.mg-logos{display:flex;flex-shrink:0}.mg-logo{width:2rem;height:2rem;margin-left:-0.25rem;border-radius:999px;background:#fff;box-shadow:0 0 0 2px #f5f6fa;overflow:hidden;opacity:0.85;animation:mg-lit 24s ease-in-out infinite}.mg-logo:first-child{margin-left:0}.dark .mg-logo{box-shadow:0 0 0 2px #0e111b}.mg-logo img{display:block;width:100%;height:100%;object-fit:cover;margin:0!important;border-radius:0!important}@keyframes mg-lit{0%,14%,100%{opacity:0.85}6%,8%{opacity:1}}.mg-flow{position:relative;flex:1;height:2px;min-width:3rem;border-radius:2px;background:repeating-linear-gradient(90deg, rgba(36, 97, 237, 0.25) 0 6px, transparent 6px 11px);overflow:hidden}.mg-beam{position:absolute;top:0;left:0;width:30%;height:100%;background:linear-gradient(90deg, transparent, rgba(36, 97, 237, 0.4));animation:mg-beam 7s ease-in-out infinite}@keyframes mg-beam{from{transform:translateX(-100%)}to{transform:translateX(340%)}}.mg-z{flex-shrink:0;width:2.5rem;height:2.5rem;border-radius:0.75rem;background:#2461ED;display:flex;align-items:center;justify-content:center;box-shadow:0 8px 20px -8px rgba(36, 97, 237, 0.6)}.mg-z svg{width:1.3rem;height:1.3rem;fill:#fff}.mg-steps{display:flex;flex-direction:column;gap:0.5rem;padding:1rem 1.25rem 1.125rem}.mg-step{display:flex;align-items:center;gap:0.75rem}.mg-num{flex-shrink:0;width:1.4rem;height:1.4rem;border-radius:999px;background:rgba(36, 97, 237, 0.1);color:#2461ED;font-size:0.75rem;font-weight:600;display:flex;align-items:center;justify-content:center}.dark .mg-num{background:rgba(107, 155, 255, 0.15);color:#9dbcff}.mg-label{flex-shrink:0;width:8.5rem;font-family:\"Aeonik Pro Var\", \"Aeonik Pro\", sans-serif;font-weight:540;font-size:0.9375rem}.mg-copy{flex:1;min-width:0;display:flex;align-items:center;gap:0.5rem;padding:0.5rem 0.5rem 0.5rem 0.75rem;border-radius:0.65rem;background:#f4f4f5;border:1px solid transparent;color:#18181b;font-size:0.875rem;text-align:left;cursor:pointer;transition:border-color 0.15s ease, background-color 0.15s ease}.mg-copy:hover{border-color:rgba(36, 97, 237, 0.35);background:#f7f8fc}.dark .mg-copy{background:rgba(255, 255, 255, 0.05);color:#e4e4e7}.dark .mg-copy:hover{border-color:rgba(107, 155, 255, 0.4)}.mg-copy.code{font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;font-size:0.8125rem}.mg-prompt{color:#2461ED}.dark .mg-prompt{color:#6b9bff}.mg-text{flex:1;min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.mg-icon{flex-shrink:0;width:1.6rem;height:1.6rem;border-radius:0.45rem;display:flex;align-items:center;justify-content:center;color:#71717a}.mg-icon.done{color:#16a34a}.mg-icon svg{width:0.95rem;height:0.95rem;fill:none;stroke:currentColor;stroke-width:1.8;stroke-linecap:round;stroke-linejoin:round}@media (max-width: 640px){.mg-step{flex-wrap:wrap}.mg-label{width:auto}.mg-copy{flex-basis:100%}.mg-logo:nth-child(n+6){display:none}}@media (prefers-reduced-motion: reduce){.mg-logo,.mg-beam{animation:none}.mg-logo{opacity:1;filter:none}}"}]}
{"page":{"pagePath":"error-handling","slug":"/error-handling","pageMetadata":{"title":"Error handling and status codes","sidebarTitle":"Errors","description":"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.","href":"/error-handling"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Tip}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Zerion API uses standard HTTP status codes and returns structured error responses. This page covers what to expect and how to handle errors gracefully.`}),`\n`,_jsx(Heading,{level:`2`,id:`error-response-format`,children:`Error response format`}),`\n`,_jsxs(_components.p,{children:[`All errors return a JSON object with an `,_jsx(_components.code,{children:`errors`}),` array:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Short error description\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"A longer explanation of what went wrong\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`http-status-codes`,children:`HTTP status codes`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:`Meaning`}),_jsx(_components.th,{children:`When it happens`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`200`})}),_jsx(_components.td,{children:`Success`}),_jsx(_components.td,{children:`Request completed successfully`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`202`})}),_jsx(_components.td,{children:`Accepted`}),_jsxs(_components.td,{children:[`NFT endpoints only: the wallet’s NFTs are still being indexed. Retry with backoff until you get `,_jsx(_components.code,{children:`200`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`400`})}),_jsx(_components.td,{children:`Bad Request`}),_jsx(_components.td,{children:`Malformed parameters. Check filter values, missing required fields, or invalid formats`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`401`})}),_jsx(_components.td,{children:`Unauthorized`}),_jsx(_components.td,{children:`Missing or invalid API key`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`404`})}),_jsx(_components.td,{children:`Not Found`}),_jsx(_components.td,{children:`The requested resource doesn’t exist (single-resource endpoints only)`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`422`})}),_jsx(_components.td,{children:`Unprocessable Entity`}),_jsx(_components.td,{children:`The request cannot be served, and retrying will not change that`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`429`})}),_jsx(_components.td,{children:`Too Many Requests`}),_jsx(_components.td,{children:`Rate limit exceeded`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`500`})}),_jsx(_components.td,{children:`Server Error`}),_jsx(_components.td,{children:`Unexpected error on Zerion’s side. Safe to retry with backoff`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`503`})}),_jsx(_components.td,{children:`Service Unavailable`}),_jsxs(_components.td,{children:[`Data is still being prepared. Retry after the delay in the `,_jsx(_components.code,{children:`Retry-After`}),` header`]})]})]})]}),`\n`,_jsx(Heading,{level:`3`,id:`400-bad-request`,children:`400 - Bad Request`}),`\n`,_jsxs(_components.p,{children:[`Returned when query parameters are malformed or invalid. Check the `,_jsx(_components.code,{children:`detail`}),` field for specifics.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Malformed parameter was sent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"chain {invalidchain} is not supported\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`Common causes:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Invalid `,_jsx(_components.code,{children:`filter[chain_ids]`}),` value (e.g., a chain ID that doesn’t exist)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`page[size]`}),` outside the allowed range (the maximum varies by endpoint)`]}),`\n`,_jsxs(_components.li,{children:[`Missing required parameters (e.g., `,_jsx(_components.code,{children:`filter[references]`}),` on the NFTs endpoint)`]}),`\n`,_jsxs(_components.li,{children:[`Malformed `,_jsx(_components.code,{children:`filter[min_mined_at]`}),` timestamp (must be exactly 13 digits, in milliseconds)`]}),`\n`,_jsx(_components.li,{children:`An address Zerion doesn’t track (see below)`}),`\n`]}),`\n`,_jsx(Heading,{level:`4`,id:`untracked-addresses`,children:`Untracked addresses`}),`\n`,_jsx(_components.p,{children:`The PnL, transactions and NFT endpoints only accept addresses that behave like user wallets, and reject anything else before doing any work:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Malformed parameter was sent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"address 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 is not trackable\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Rejected: contracts that aren’t recognized smart-contract wallets (token contracts, routers, vaults), burn and reserved addresses, and high-volume addresses such as exchange hot wallets and mining pools. Smart-contract wallets are fine: Safe, Coinbase Smart Wallet, ERC-4337 accounts and EIP-7702 delegated EOAs all work.`}),`\n`,_jsx(_components.p,{children:`Recognition works by wallet implementation, so a newly deployed Safe is tracked immediately with no setup. Trackability is decided per address, not per chain. If you need a specific address, or a wallet implementation Zerion doesn’t recognize yet, contact support.`}),`\n`,_jsx(Heading,{level:`3`,id:`401-unauthorized`,children:`401 - Unauthorized`}),`\n`,_jsx(_components.p,{children:`Returned when the API key is missing, invalid, or incorrectly encoded.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Unauthorized Error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"The API key is invalid, please, make sure that you are using a valid key\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`Common causes:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Missing `,_jsx(_components.code,{children:`Authorization`}),` header`]}),`\n`,_jsxs(_components.li,{children:[`API key not Base64-encoded correctly. Remember to append a colon: `,_jsx(_components.code,{children:`base64(\"your_key:\")`})]}),`\n`,_jsx(_components.li,{children:`Expired or revoked API key`}),`\n`]}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`Test your encoding: `,_jsx(_components.code,{children:`echo -n \"your_api_key:\" | base64`}),` should produce the value you pass after `,_jsx(_components.code,{children:`Basic `}),`.`]})}),`\n`,_jsx(Heading,{level:`3`,id:`404-not-found`,children:`404 - Not Found`}),`\n`,_jsx(_components.p,{children:`Returned on single-resource endpoints when the ID doesn’t match any record.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Requested fungible was not found\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"You have requested fungible which does not exist\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`This only applies to endpoints like `,_jsx(_components.code,{children:`/v1/fungibles/{fungible_id}`}),` or `,_jsx(_components.code,{children:`/v1/nfts/{nft_id}`}),`. List endpoints return an empty `,_jsx(_components.code,{children:`data`}),` array instead of a 404.`]}),`\n`,_jsx(Heading,{level:`3`,id:`422-unprocessable-entity`,children:`422 - Unprocessable Entity`}),`\n`,_jsxs(_components.p,{children:[`Returned when a request cannot be served and retrying will not change that. Unlike a `,_jsx(_components.code,{children:`503`}),`, it carries no `,_jsx(_components.code,{children:`Retry-After`}),` header.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"This request is not supported\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"This request cannot be processed, and retrying will not help. Please contact support if you need it enabled.\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The PnL endpoints (`,_jsx(_components.code,{children:`/v1/wallets/{address}/pnl`}),` and `,_jsx(_components.code,{children:`/v1/wallet-sets/pnl`}),`) return it for wallets with more than 1 million actions, which are too large for PnL to be calculated. The limit is counted per address, so a wallet set fails if any one of its addresses is over it.`]}),`\n`,_jsx(_components.p,{children:`Don’t retry, and don’t cache the result against the address: the same address can return a different status later.`}),`\n`,_jsx(Heading,{level:`3`,id:`429-too-many-requests`,children:`429 - Too Many Requests`}),`\n`,_jsx(_components.p,{children:`Returned when you exceed your plan’s rate limit.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Too many requests\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Your request had been throttled\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Implement exponential backoff when retrying. For header details and retry guidance, see `,_jsx(_components.a,{href:`/rate-limits`,children:`Rate limits`}),`. If you’re hitting limits consistently, upgrade your plan in the `,_jsx(_components.a,{href:`https://dashboard.zerion.io`,children:`Dashboard`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`500-server-error`,children:`500 - Server Error`}),`\n`,_jsx(_components.p,{children:`Returned when something unexpected goes wrong on Zerion’s side.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Internal Server Error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"An unexpected error occurred\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`These errors are safe to retry. Use exponential backoff (e.g., 1s, 2s, 4s) and cap your retries. If the error persists, reach out to support.`}),`\n`,_jsx(Heading,{level:`3`,id:`503-service-unavailable`,children:`503 - Service Unavailable`}),`\n`,_jsxs(_components.p,{children:[`Returned when the data you asked for is still being prepared. The PnL, wallet positions and fungible chart endpoints compute a wallet’s state on the first request, and answer with a `,_jsx(_components.code,{children:`503`}),` while that runs.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"errors\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Service is temporarily unavailable\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Please, retry later (check the Retry-After header)\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`This always includes a `,_jsx(_components.code,{children:`Retry-After`}),` header, typically 10 seconds. Wait for it rather than retrying immediately, and cap your attempts.`]}),`\n`,_jsx(Heading,{level:`2`,id:`best-practices`,children:`Best practices`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`Retry on `,_jsx(_components.code,{children:`429`}),`, `,_jsx(_components.code,{children:`500`}),` and `,_jsx(_components.code,{children:`503`}),`.`]}),` Do not retry `,_jsx(_components.code,{children:`400`}),`, `,_jsx(_components.code,{children:`401`}),` or `,_jsx(_components.code,{children:`422`}),`. These return the same result however many times you send them.`]}),`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`Respect `,_jsx(_components.code,{children:`Retry-After`}),`.`]}),` On a `,_jsx(_components.code,{children:`503`}),` it tells you how long the data needs; retrying sooner burns your rate limit.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Use exponential backoff.`}),` When retrying, increase the delay between attempts exponentially (e.g., 1s, 2s, 4s) to avoid overwhelming the API.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Validate parameters before sending.`}),` Check that `,_jsx(_components.code,{children:`page[size]`}),` is within the endpoint’s allowed range, timestamps are 13-digit milliseconds, and chain IDs match the `,_jsx(_components.a,{href:`/supported-blockchains`,children:`supported chains`}),`. This avoids unnecessary `,_jsx(_components.code,{children:`400`}),` errors.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Use webhooks instead of polling.`}),` If you need to monitor wallet activity, use `,_jsx(_components.a,{href:`/api-reference/subscriptions-to-transactions/create-subscription`,children:`transaction subscriptions`}),` instead of polling. This reduces API usage and gives you faster notifications.`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Error handling and status codes","sidebarTitle":"Errors","description":"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.","href":"/error-handling"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Error response format","slug":"error-response-format","depth":2,"children":[]},{"title":"HTTP status codes","slug":"http-status-codes","depth":2,"children":[{"title":"400 - Bad Request","slug":"400-bad-request","depth":3,"children":[]},{"title":"Untracked addresses","slug":"untracked-addresses","depth":4,"children":[]},{"title":"401 - Unauthorized","slug":"401-unauthorized","depth":3,"children":[]},{"title":"404 - Not Found","slug":"404-not-found","depth":3,"children":[]},{"title":"422 - Unprocessable Entity","slug":"422-unprocessable-entity","depth":3,"children":[]},{"title":"429 - Too Many Requests","slug":"429-too-many-requests","depth":3,"children":[]},{"title":"500 - Server Error","slug":"500-server-error","depth":3,"children":[]},{"title":"503 - Service Unavailable","slug":"503-service-unavailable","depth":3,"children":[]}]},{"title":"Best practices","slug":"best-practices","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/zerion-f99485ad/f7d9c934821323b5/api-reference.js","/_mintlify/custom/zerion-f99485ad/4972e5c7bcb8428c/changelog.js","/_mintlify/custom/zerion-f99485ad/04f750f612fd0882/toc-actions.js"],"subdomain":"zerion-f99485ad","siteName":"Zerion API","title":"Error handling and status codes - Zerion API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-13T16:05:49.355Z","originalFileLocation":"error-handling.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Zerion API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Error handling and status codes - Zerion API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Zerion API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://developers.zerion.io/error-handling\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://zerion-f99485ad.mintlify.site/_mintlify/api/og/v2?division=Core+concepts\u0026amp;title=Error+handling+and+status+codes\u0026amp;description=Understand+Zerion+API+error+responses%2C+HTTP+status+codes%2C+rate-limit+errors%2C+and+best+practices+for+retry+logic+and+exponential+backoff+in+production+apps.\u0026amp;theme=d49b1634eaf03f1d6a16fb4e\u0026amp;signature=5ebff42db400b4665ca70998faa4143a6a25474d0d4a65c4d8e2747eaa6a88a5\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Error handling and status codes - Zerion API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://zerion-f99485ad.mintlify.site/_mintlify/api/og/v2?division=Core+concepts\u0026amp;title=Error+handling+and+status+codes\u0026amp;description=Understand+Zerion+API+error+responses%2C+HTTP+status+codes%2C+rate-limit+errors%2C+and+best+practices+for+retry+logic+and+exponential+backoff+in+production+apps.\u0026amp;theme=d49b1634eaf03f1d6a16fb4e\u0026amp;signature=5ebff42db400b4665ca70998faa4143a6a25474d0d4a65c4d8e2747eaa6a88a5\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/zerion-f99485ad/VzHsQ_h3ouhCUDnV/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Zerion API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2461ED\">\u003clink data-mint-head rel=\"canonical\" href=\"https://developers.zerion.io/error-handling\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/error-handling.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://developers.zerion.io/#organization\",\"name\":\"Zerion API\",\"url\":\"https://developers.zerion.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/zerion-f99485ad/7LRY3a3Ldx_ROK8O/logo/light.svg?fit=max\u0026auto=format\u0026n=7LRY3a3Ldx_ROK8O\u0026q=85\u0026s=f451fe390bc92095f03123a8f7d40a7d\"}},{\"@type\":\"WebSite\",\"@id\":\"https://developers.zerion.io#website\",\"name\":\"Zerion API\",\"url\":\"https://developers.zerion.io\",\"publisher\":{\"@id\":\"https://developers.zerion.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://developers.zerion.io/error-handling#webpage\",\"url\":\"https://developers.zerion.io/error-handling\",\"name\":\"Error handling and status codes\",\"description\":\"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.\",\"dateModified\":\"2026-11-13T16:05:49.355Z\",\"isPartOf\":{\"@id\":\"https://developers.zerion.io#website\"},\"breadcrumb\":{\"@id\":\"https://developers.zerion.io/error-handling#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://developers.zerion.io/error-handling#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Core concepts\",\"item\":\"https://developers.zerion.io/supported-blockchains\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Error handling and status codes\",\"item\":\"https://developers.zerion.io/error-handling\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://developers.zerion.io/error-handling#article\",\"headline\":\"Error handling and status codes\",\"name\":\"Error handling and status codes\",\"description\":\"Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.\",\"url\":\"https://developers.zerion.io/error-handling\",\"mainEntityOfPage\":{\"@id\":\"https://developers.zerion.io/error-handling#webpage\"},\"dateModified\":\"2026-11-13T16:05:49.355Z\",\"publisher\":{\"@id\":\"https://developers.zerion.io/#organization\"},\"isPartOf\":{\"@id\":\"https://developers.zerion.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Zerion API\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Zerion API\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/error-handling.md","siteName":"Zerion API","nav":{"global":null,"tabs":[{"tab":"Home","groups":[{"group":"Get started","pages":[{"title":"Zerion API documentation","sidebarTitle":"Introduction","href":"/introduction"},{"title":"Quickstart","href":"/quickstart"},{"title":"Authentication","href":"/authentication"},{"group":"Build with AI","pages":[{"title":"Build AI agents with onchain data","sidebarTitle":"Overview","href":"/build-with-ai/overview"},{"title":"Zerion CLI and agent skills for AI coding tools","sidebarTitle":"Zerion CLI","href":"/build-with-ai/zerion-cli"},{"title":"x402 payments: pay-per-request Zerion API access","sidebarTitle":"x402 payments","href":"/build-with-ai/x402"},{"title":"MPP payments: pay-per-request Zerion API access","sidebarTitle":"MPP payments","href":"/build-with-ai/mpp"},{"title":"Model Context Protocol (MCP) server","sidebarTitle":"MCP server","href":"/build-with-ai/mcp"}]},{"title":"Migrate to Zerion API","sidebarTitle":"Migrate to Zerion","href":"/migrate-to-zerion"}]},{"group":"Core concepts","pages":[{"title":"Supported blockchains and chain IDs for Zerion API","sidebarTitle":"Supported blockchains","href":"/supported-blockchains"},{"title":"Endpoints and response schema","sidebarTitle":"Endpoints and schema","href":"/endpoints-and-schema"},{"title":"Pagination, filtering, sorting, and currency","sidebarTitle":"Pagination and filtering","description":"Paginate through results with cursors, filter by chain, position type, or asset, sort responses, and switch currencies across Zerion API endpoints.","href":"/pagination-and-filtering"},{"title":"Error handling and status codes","sidebarTitle":"Errors","href":"/error-handling"},{"title":"Rate limits and throttling","sidebarTitle":"Rate limits","description":"How Zerion API rate limits work, which response headers to inspect, how to detect 429 responses, and best practices for retries with exponential backoff.","href":"/rate-limits"},{"title":"Webhooks for real-time wallet transaction notifications","sidebarTitle":"Webhooks","href":"/webhooks"},{"title":"Kafka streaming for onchain events","sidebarTitle":"Kafka streaming","href":"/streaming"},{"title":"Spam token filtering","href":"/spam-filtering"},{"title":"Real-world asset (RWA) classification","sidebarTitle":"RWA classification","href":"/rwa-classification"}]},{"group":"Migrating to Zerion API","pages":[{"title":"Migrate from Zapper to Zerion API","sidebarTitle":"From Zapper","href":"/migrate-from-zapper"},{"title":"Migrate from Dune SIM to Zerion API","sidebarTitle":"From Dune SIM","href":"/migrate-from-sim"},{"title":"Migrate from Mobula to Zerion API","sidebarTitle":"From Mobula","href":"/migrate-from-mobula"},{"title":"Migrate from OneBalance to Zerion API","sidebarTitle":"From OneBalance","href":"/migrate-from-onebalance"},{"title":"Migrate from DeBank Cloud to Zerion API","sidebarTitle":"From DeBank","href":"/migrate-from-debank"},{"title":"Migrate from Allium to Zerion API","sidebarTitle":"From Allium","href":"/migrate-from-allium"},{"title":"Migrate from GoldRush (Covalent) to Zerion API","sidebarTitle":"From GoldRush","href":"/migrate-from-goldrush"},{"title":"Migrate from Moralis to Zerion API","sidebarTitle":"From Moralis","href":"/migrate-from-moralis"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/wallets/get-wallet-balance-chart"}]},{"tab":"Recipes","pages":[{"title":"Recipes","href":"/recipes"}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]},{"tab":"Case studies","href":"https://zerion.io/blog/tag/zerion-api/"}]},"basePath":"","title":"Error handling and status codes - Zerion API","deploymentId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","buildId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","dynamics":[],"chunks":[]}