{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","eventexplorer","eventkind"]},"type":"markdown"},"seo":{"title":"Errors - API error reference","projectTitle":"Vilna Docs","description":"How Vilna API errors work: the RFC 7807 problem+json body, the machine-readable code to branch on, and a status-code reference.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-errors.png","meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Vilna Documentation"},{"name":"og:image:width","content":"1200"},{"name":"og:image:height","content":"630"},{"name":"twitter:card","content":"summary_large_image"},{"name":"robots","content":"max-image-preview:large"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna Platform API monitors public blockchain activity, balances and invoices and delivers signed webhooks. It does not sign or broadcast transactions. VKS separately coordinates account setup, signer approvals and signing, retains signed results and can submit a complete transaction to a node. Node acceptance is not blockchain confirmation. Each API uses its own scoped credential in X-Api-Key. Workspace setup and VKS-key issuance start in the Dashboard.\n","details":{"content":"**Platform monitoring.** Platform observes merchant-controlled addresses,\nsupplied directly or derived from the merchant's extended public key (xPub).\nInvoices report incoming on-chain activity; they do not initiate transfers.\n\n**APIs and their credentials.**\n\n- Platform API (api.vilna.io) - monitor addresses and extended public keys, read\n  balances and transactions, reconcile incoming payments, create invoices, and\n  receive events.\n- Blockchain RPC (rpc.vilna.io) - JSON-RPC and gRPC node access across every\n  supported network behind one key.\n- Management API (mgmt.vilna.io) - published workspace, project, member and key\n  operations, with Dashboard bootstrap and credential grant limits.\n- VKS API (vks.vilna.io) - workspace signers, vaults, accounts, signing requests,\n  signed results and optional asynchronous send. Uses a Dashboard-issued VKS key\n  with vks:access; the public Management API has no VKS-key issuance route.\n\n**Pages with no markdown source**, so they cannot be linked below:\n\n- Product overview: https://docs.vilna.io/\n- All guides: https://docs.vilna.io/guides\n"},"excludeFiles":["legal/terms.md","legal/privacy.md","legal/cookies.md","@l10n/ru/legal/terms.md","@l10n/ru/legal/privacy.md","@l10n/ru/legal/cookies.md"],"sections":[{"title":"Getting Started","description":"What the platform is, how to make a first call, and answers to common questions","includeFiles":["get-started/quickstart.md","get-started/dashboard.md","get-started/core-concepts.md","get-started/members.md","get-started/faq.md"]},{"title":"API Reference","description":"Authentication, permissions, idempotency, errors, standards, and per-service endpoint documentation","includeFiles":["apis/authentication.md","apis/permissions.md","apis/idempotency.md","apis/errors.md","apis/standards.md","apis/networks.md","apis/platform/@v2/index.md","apis/platform/@v2/webhooks.md","apis/platform/@v2/api.yaml","apis/mgmt/index.md","apis/mgmt/api.yaml","apis/vks/index.md","apis/vks/api.yaml","apis/rpc/index.md","apis/rpc/json-rpc.md","apis/rpc/grpc.md"]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, and tooling","includeFiles":["guides/events.md","guides/channels.md","guides/tokens.md","guides/integration-patterns.md","guides/mcp.md","guides/simulation.md","guides/invoices.md","guides/vks.md"]},{"title":"Trust and custody","description":"The non-custodial model in plain terms","includeFiles":["legal/non-custodial.md"]},{"title":"Optional","description":"Background reading and release history","includeFiles":["get-started/blockchain-basics.md","changelog.md"]}]},"priority":0.5,"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Errors"}]},{"@type":"TechArticle","headline":"Errors - API error reference","description":"How Vilna API errors work: the RFC 7807 problem+json body, the machine-readable code to branch on, and a status-code reference.","url":"https://docs.vilna.io/apis/errors","datePublished":"2025-09-17","dateModified":"2026-11-01","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-errors.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors","__idx":0},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Platform, Management and VKS HTTP APIs use Problem Details (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]},"). Check the status and machine-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," together with the operation you called. Codes are open strings, not an exhaustive enum; keep a fallback for unfamiliar values. Human-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," are not branching keys."]},{"$$mdtype":"Tag","name":"QuickFacts","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"alert"},"children":["Problem Details · problem+json"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"code"},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"search"},"children":["Schema-specific fields"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"server"},"children":["RPC: protocol errors"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"body","level":2,"__idx":1},"children":["The error body "]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URI identifying the problem category"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable label"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Machine-readable service code; sometimes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unspecified"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Explanation for this occurrence"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instance"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["no"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Occurrence identifier; include it in support requests"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#not-found\",\n  \"title\": \"Not Found\",\n  \"status\": 404,\n  \"code\": \"address.not_found\",\n  \"detail\": \"address not found\",\n  \"instance\": \"/traces/0123456789abcdef0123456789abcdef\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the schema declared by the operation for fields such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window_seconds"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"statuses","level":2,"__idx":2},"children":["Status codes "]},{"$$mdtype":"Tag","name":"EventExplorer","attributes":{},"children":[{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"invalid-request","name":"400","desc":"Invalid Request"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fix malformed input. Platform and Management may use different codes for the same status."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#invalid-request\",\n  \"title\": \"Invalid Request\",\n  \"status\": 400,\n  \"code\": \"request.malformed\",\n  \"detail\": \"The request could not be decoded.\",\n  \"instance\": \"/traces/0123456789abcdef0123456789abcdef\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"unauthorized","name":"401","desc":"Unauthorized"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the credential and its service."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#unauthorized\",\n  \"title\": \"Unauthorized\",\n  \"status\": 401,\n  \"code\": \"unspecified\",\n  \"detail\": \"You are not authorized to access this resource. If the problem persists, please contact our support team.\",\n  \"instance\": \"/unauthorized?method=createInvoice\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"forbidden","name":"403","desc":"Forbidden"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The caller lacks access. Check current permissions; an idempotency key grants no access."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"not-found","name":"404","desc":"Not Found"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The resource is absent or not visible to this caller."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#not-found\",\n  \"title\": \"Not Found\",\n  \"status\": 404,\n  \"code\": \"project.not_found\",\n  \"detail\": \"project not found\",\n  \"instance\": \"/traces/0199ce911a2b7c019c2a9d0010eaa310\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"method-not-allowed","name":"405","desc":"Method Not Allowed"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a method supported by the route."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"request-canceled","name":"408","desc":"Request Canceled"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A canceled connection does not prove that a mutation failed. Retry with its original intent key and inputs when required."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"conflict","name":"409","desc":"Conflict"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The operation conflicts with resource state or its idempotency binding. Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," before deciding what to do."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#conflict\",\n  \"title\": \"Conflict\",\n  \"status\": 409,\n  \"code\": \"invoice.address_occupied\",\n  \"detail\": \"address already has an active invoice with different parameters\",\n  \"instance\": \"/traces/0123456789abcdef0123456789abcdef\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"request-too-large","name":"413","desc":"Request Too Large"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reduce the payload to the endpoint’s size limit."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"precondition","name":"422","desc":"Precondition Failed"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A business rule or state precondition rejected the request. Fix that condition before retrying."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#precondition\",\n  \"title\": \"Precondition Failed\",\n  \"status\": 422,\n  \"code\": \"invoice.not_cancellable\",\n  \"detail\": \"invoice cannot be cancelled in current status\",\n  \"instance\": \"/traces/0123456789abcdef0123456789abcdef\",\n  \"fields\": [\n    {\n      \"name\": \"status\",\n      \"reason\": \"confirmed\"\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"too-many-requests","name":"429","desc":"Too Many Requests"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This can mean a resource quota, an action window or a resend cooldown. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#rate-limits"},"children":["Rate limits"]}," for the different recovery paths."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"not-implemented","name":"501","desc":"Not Implemented"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The operation is unsupported. Repeating unchanged input will not add support."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"bad-gateway","name":"502","desc":"Bad Gateway"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A required service was unavailable. Retry with backoff and the same mutation intent."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"service-unavailable","name":"503","desc":"Service Unavailable"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The operation is temporarily unavailable. Retry with backoff, preserving the mutation key and inputs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#service-unavailable\",\n  \"title\": \"Service Unavailable\",\n  \"status\": 503,\n  \"code\": \"service.temporarily_unavailable\",\n  \"detail\": \"The operation is temporarily unavailable. Please try again later.\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"gateway-timeout","name":"504","desc":"Gateway Timeout"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request exceeded its deadline. The outcome may be uncertain; preserve the original intent on retry."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"internal-error","name":"5xx","desc":"Server Error"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An unexpected server error does not establish whether a side effect occurred. Use backoff and the original mutation key; reconcile if its replay is unavailable."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"idempotency-conflicts","level":3,"__idx":3},"children":["Idempotency conflicts "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The conflicts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_in_progress"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_request_mismatch"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_result_expired"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_result_unavailable"]}," require different recovery steps. Keep the original key and request inputs; never automatically substitute a new key for an unknown outcome. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/idempotency#recovery"},"children":["Idempotency"]}," for scope, windows and per-service recovery. An invalid or repeated header returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", rather than an idempotency ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"validation","level":2,"__idx":4},"children":["Validation fields "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," schemas can include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]},", an array of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"name\": \"…\", \"reason\": \"…\" }"]}," entries. Entries can describe invalid input or diagnostic state, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name: status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason: confirmed"]}," when an invoice cannot be cancelled. A malformed JSON request need not identify a single field."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"rate-limits","level":2,"__idx":5},"children":["Rate limits and quotas "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"resource-capacity","__idx":6},"children":["Resource capacity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["QuotaExceededProblem"]}," adds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]},", the effective configured resource limit in the operation’s scope. It is not usage or remaining capacity. Waiting does not free capacity: reduce usage where the product permits it, or arrange a limit change. A zero limit prohibits new admissions without disabling resources already held."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#too-many-requests\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"code\": \"address.quota_exceeded\",\n  \"detail\": \"the project has reached its address limit\",\n  \"max\": 100\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#too-many-requests\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"code\": \"project.limit_exceeded\",\n  \"detail\": \"project limit exceeded\",\n  \"max\": 2\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"time-windows","__idx":7},"children":["Time windows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For balance refresh, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RateLimitExceededProblem"]}," adds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window_seconds"]},". The window duration is not the remaining wait. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," gives whole seconds until an earliest retry when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max > 0"]}," and the deadline is known; it is omitted for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max: 0"]}," or an unknown deadline. A zero limit requires a policy change, not backoff alone. The next attempt checks capacity again."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#too-many-requests\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"code\": \"balance.refresh_rate_exceeded\",\n  \"detail\": \"the project has reached its balance refresh rate limit\",\n  \"max\": 1,\n  \"window_seconds\": 60\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"manual-resend-cooldown","__idx":8},"children":["Manual resend cooldown"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notification resend can return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification.resend_delayed"]},". Its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," is the rounded-up wait to the later of the delivery pause and the cooldown since the last attempt. It is a hint, not a reservation. Retry the same request and intent key after waiting. A queued/running send is instead ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 notification.send_in_progress"]},"; expired content is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 notification.payload_unavailable"]},". Inspect the notification and its logs before another action."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#too-many-requests\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"code\": \"notification.resend_delayed\",\n  \"detail\": \"notification resend is delayed\",\n  \"instance\": \"/traces/0123456789abcdef0123456789abcdef\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"vks-problems","level":2,"__idx":9},"children":["VKS problem types "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These type fragments are used by public VKS response examples. They are examples of open codes, not the complete set of possible responses. Preserve the supplied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," URI when logging an error."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"backend.failure","level":3,"__idx":10},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["backend.failure"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unexpected failure; retry the original intent with backoff, then reconcile if the outcome remains uncertain."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#backend.failure\",\n  \"title\": \"Internal Server Error\",\n  \"status\": 500,\n  \"code\": \"backend.failure\",\n  \"detail\": \"internal error\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"request.invalid","level":3,"__idx":11},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request.invalid"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Correct the request against the operation schema."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#request.invalid\",\n  \"title\": \"Bad Request\",\n  \"status\": 400,\n  \"code\": \"request.invalid\",\n  \"detail\": \"invalid request\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.not_found","level":3,"__idx":12},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.not_found"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the transaction identity and workspace access."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.not_found\",\n  \"title\": \"Not Found\",\n  \"status\": 404,\n  \"code\": \"transaction.not_found\",\n  \"detail\": \"transaction not found\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"account.state_invalid","level":3,"__idx":13},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.state_invalid"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read the account state and check which states the operation permits. Wait only if setup is still progressing; some operations remain unavailable for an active account."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#account.state_invalid\",\n  \"title\": \"Conflict\",\n  \"status\": 409,\n  \"code\": \"account.state_invalid\",\n  \"detail\": \"account state does not allow this operation\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.state_invalid","level":3,"__idx":14},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.state_invalid"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read the transaction state before choosing another action."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.state_invalid\",\n  \"title\": \"Conflict\",\n  \"status\": 409,\n  \"code\": \"transaction.state_invalid\",\n  \"detail\": \"transaction state does not allow this operation\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.send_in_progress","level":3,"__idx":15},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.send_in_progress"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A send is already pending. Check send history rather than queueing another send."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.send_in_progress\",\n  \"title\": \"Conflict\",\n  \"status\": 409,\n  \"code\": \"transaction.send_in_progress\",\n  \"detail\": \"transaction has a pending send attempt\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.already_sent","level":3,"__idx":16},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.already_sent"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The node already accepted the transaction. Check send history; this does not establish chain confirmation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.already_sent\",\n  \"title\": \"Conflict\",\n  \"status\": 409,\n  \"code\": \"transaction.already_sent\",\n  \"detail\": \"transaction was already accepted by RPC\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.send_limit_exceeded","level":3,"__idx":17},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.send_limit_exceeded"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]}," is the transaction’s shared manual and automatic attempt limit. Waiting alone does not reset it."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.send_limit_exceeded\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"code\": \"transaction.send_limit_exceeded\",\n  \"detail\": \"transaction send limit exceeded\",\n  \"max\": 10\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"signer.limit_exceeded","level":3,"__idx":18},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signer.limit_exceeded"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]}," is the workspace limit for registered signers plus unexpired invitations. Offline signers still count. Remove unused invitations or signers that are eligible for deletion, or contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@vilna.io"},"children":["support@vilna.io"]}," about the limit."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#signer.limit_exceeded\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"code\": \"signer.limit_exceeded\",\n  \"detail\": \"workspace signer limit exceeded\",\n  \"max\": 10\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.send_unsupported","level":3,"__idx":19},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.send_unsupported"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The result is not a broadcastable transaction; an ingredient cannot be sent through this action."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.send_unsupported\",\n  \"title\": \"Unprocessable Entity\",\n  \"status\": 422,\n  \"code\": \"transaction.send_unsupported\",\n  \"detail\": \"signed result is not a broadcastable transaction\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"transaction.rpc_not_configured","level":3,"__idx":20},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.rpc_not_configured"]}," "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["VKS cannot submit transactions to this network because no node is configured for it. Contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@vilna.io"},"children":["support@vilna.io"]}," about network availability before retrying."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://docs.vilna.io/apis/errors#transaction.rpc_not_configured\",\n  \"title\": \"Unprocessable Entity\",\n  \"status\": 422,\n  \"code\": \"transaction.rpc_not_configured\",\n  \"detail\": \"RPC is not configured for this network\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"services","level":2,"__idx":21},"children":["Errors across services "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Platform, Management and VKS use the HTTP problem envelope above, with service-specific codes and extensions. Blockchain RPC has its own protocol errors; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/rpc/json-rpc#error-handling"},"children":["JSON-RPC error handling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"blockchain-rpc","__idx":22},"children":["Blockchain RPC"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A rate-limited JSON-RPC call returns the following protocol error; gRPC returns HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," with an empty body."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"jsonrpc\": \"2.0\",\n  \"error\": {\n    \"code\": -32005,\n    \"message\": \"rate limit exceeded\",\n    \"data\": {\n      \"source\": \"vilna\"\n    }\n  },\n  \"id\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-*"]}," headers. Use the response-specific ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," rules above; do not treat every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," as a temporary window. For retryable network and server failures, use backoff and preserve mutation intent."]}]},"headings":[{"value":"Errors","id":"errors","depth":1},{"value":"The error body","id":"body","depth":2},{"value":"Status codes","id":"statuses","depth":2},{"value":"Idempotency conflicts","id":"idempotency-conflicts","depth":3},{"value":"Validation fields","id":"validation","depth":2},{"value":"Rate limits and quotas","id":"rate-limits","depth":2},{"value":"Resource capacity","id":"resource-capacity","depth":3},{"value":"Time windows","id":"time-windows","depth":3},{"value":"Manual resend cooldown","id":"manual-resend-cooldown","depth":3},{"value":"VKS problem types","id":"vks-problems","depth":2},{"value":"backend.failure","id":"backend.failure","depth":3},{"value":"request.invalid","id":"request.invalid","depth":3},{"value":"transaction.not_found","id":"transaction.not_found","depth":3},{"value":"account.state_invalid","id":"account.state_invalid","depth":3},{"value":"transaction.state_invalid","id":"transaction.state_invalid","depth":3},{"value":"transaction.send_in_progress","id":"transaction.send_in_progress","depth":3},{"value":"transaction.already_sent","id":"transaction.already_sent","depth":3},{"value":"transaction.send_limit_exceeded","id":"transaction.send_limit_exceeded","depth":3},{"value":"signer.limit_exceeded","id":"signer.limit_exceeded","depth":3},{"value":"transaction.send_unsupported","id":"transaction.send_unsupported","depth":3},{"value":"transaction.rpc_not_configured","id":"transaction.rpc_not_configured","depth":3},{"value":"Errors across services","id":"services","depth":2},{"value":"Blockchain RPC","id":"blockchain-rpc","depth":3}],"frontmatter":{"seo":{"title":"Errors - API error reference","description":"How Vilna API errors work: the RFC 7807 problem+json body, the machine-readable code to branch on, and a status-code reference.","priority":0.5,"image":"https://cdn.vilna.io/docs/og/26103121/en/apis-errors.png","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Errors"}]},{"@type":"TechArticle","headline":"Errors - API error reference","description":"How Vilna API errors work: the RFC 7807 problem+json body, the machine-readable code to branch on, and a status-code reference.","url":"https://docs.vilna.io/apis/errors","datePublished":"2025-09-17","dateModified":"2026-11-01","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-errors.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-10-31T22:26:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}