> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/errors-decimals-and-transactions.md). # Errors, decimals & transactions Preview SONIC error, retry, atomic amount, signature, transaction state, settlement and reconciliation conventions. **Status:** `Preview` Error names and state transitions are designed to remain stable, but this page does not represent the associated APIs as `Live` or `Verified` until those routes pass the owning production validation checks. ## Error contract SONIC exposes stable machine-readable error codes and request metadata. Provider/RPC/database details are normalized instead of being leaked through public responses. ```json { "error": { "code": "ENTITLEMENT_REQUIRED", "message": "A required product entitlement is missing." }, "meta": { "requestId": "req_01...", "timestamp": "", "contractVersion": "", "contractStatus": "preview" } } ``` Clients branch on `error.code`, not mutable message text. ## Auth/context/access errors | Code | HTTP | Meaning | | ------------------------- | ---: | ----------------------------------------------------- | | `UNAUTHENTICATED` | 401 | A valid signed session is required | | `SESSION_EXPIRED` | 401 | Session is expired | | `ACCOUNT_DISABLED` | 403 | Current account is suspended or disabled | | `TENANT_NOT_FOUND` | 404 | Session tenant cannot be resolved | | `TENANT_UNAVAILABLE` | 503 | Tenant is temporarily unavailable | | `WORKSPACE_NOT_FOUND` | 404 | Workspace cannot be resolved | | `WORKSPACE_REQUIRED` | 403 | Workspace context is required | | `WORKSPACE_ACCESS_DENIED` | 403 | Authenticated authority cannot access workspace scope | | `ROLE_REQUIRED` | 403 | Required role is missing | | `PERMISSION_REQUIRED` | 403 | Required permission is missing | | `ACCESS_DENIED` | 403 | General operation/resource policy denial | | `PATH_NOT_ALLOWED` | 403 | No internal route policy permits the path | | `SUBSCRIPTION_REQUIRED` | 403 | Eligible subscription required | | `ENTITLEMENT_REQUIRED` | 403 | Product entitlement missing | | `FEATURE_DISABLED` | 403 | Feature disabled by product policy | | `INVALID_PATH` | 400 | Access Context received an invalid/non-internal path | | `CONTEXT_UNAVAILABLE` | 503 | Required authoritative context unavailable | | `INTERNAL_ERROR` | 500 | Unexpected internal context failure | Subscription and entitlement failures are not rewritten as generic permission failures. Feature-disabled is not treated as permission authority. ## General HTTP semantics | HTTP | Meaning | | ---- | ----------------------------------------------------------------------------------------------------- | | 400 | malformed schema, internal path, public key or signature | | 401 | authentication/session or protected reconciliation credential required | | 403 | role, permission, workspace, subscription, entitlement, feature or verified-wallet requirement failed | | 404 | resource/tenant/workspace not found or intentionally undisclosed | | 409 | state/idempotency/signature conflict or expired/stale intent | | 422 | invalid business precondition, amount, decimals or policy input | | 429 | rate limited | | 502 | upstream provider/RPC failure | | 503 | context/provider/tenant/service unavailable | Server-side 5xx responses use safe public messages. Detailed exception/provider/audit context remains server-side. ## Retry and remediation guidance | Condition | Guidance | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `UNAUTHENTICATED` / `SESSION_EXPIRED` | Reauthenticate first; do not blindly replay money-moving requests. | | account/role/permission/workspace denial | Do not retry until authoritative access state changes. | | `SUBSCRIPTION_REQUIRED` / `ENTITLEMENT_REQUIRED` | Reconcile product access before retry. | | `FEATURE_DISABLED` | Retry only after product feature state changes. | | HTTP 409 | Refresh authoritative state/quote/intent; preserve the canonical idempotency identity for the same logical operation. | | HTTP 429 | Respect retry guidance when supplied. | | HTTP 502/503 | Retry only when safe/idempotent; financial writes keep the original operation identity. | A network retry must not create duplicate payment settlement, credit funding, reward allocation, Marketplace order or AI generation settlement. A timeout does not prove that a mutation failed. Recover the durable operation by ID or idempotency key where supported. ## Public keys and signatures * Solana public keys are base58 decoded and must be exactly **32 bytes**. * Solana transaction signatures are base58 decoded and must be exactly **64 bytes**. * A signature already bound to an intent cannot be silently reused for another business operation. * Syntax-valid keys/signatures do not prove wallet ownership, recipient suitability or successful settlement. * Wallet connection does not create authentication authority. * A signed transaction/message authorizes only the concrete content that was reviewed and signed. ## Atomic amounts and decimals Financial and chain settlement uses integer atomic values. Never use JavaScript floating-point arithmetic for ledger settlement. ``` SOL 9 USDC 6 EURC 6 SONIC decimals come from verified deployment/configuration ``` Historical records preserve the decimals, fee policy, price/quote data and other immutable policy snapshots used by the original operation. ## No fabricated zero balances A successful authoritative provider/RPC response may truthfully report zero. Provider/RPC failure or missing state is **unavailable**, not `0`. ## Transaction and chain state ``` INTENT_CREATED → TRANSACTION_PREPARED → AWAITING_SIGNATURE / SIGNED → SUBMITTED → PROCESSED → CONFIRMED → FINALIZED ``` Exceptional states include `FAILED`, `EXPIRED` and `CANCELLED`. These are network/authorization states. Business/economic state remains separate: ``` chain verification → expected-effect verification → SETTLED → RECONCILED → domain effect ``` A confirmed signature does not itself prove the expected recipient, mint/asset, atomic amount, decimals, reference or business effect. Those effects are verified independently before durable settlement/reconciliation. ## Transaction intent integrity Before signature, SONIC persists the exact operation that may be prepared: network, actor/account, payer, recipient, mint/asset, atomic amount, decimals, fees, quote/policy identity, business reference, purpose and expiry. The client must never be allowed to silently substitute a different recipient or economic amount after the intent has been reviewed. ## Settlement thresholds Different domains may require different chain thresholds. A product page must document whether its operation settles at processed, confirmed or finalized state. Higher-risk treasury/reward operations may require a stronger threshold than ordinary application actions. Chain threshold alone is still insufficient without expected-effect verification. ## Refund policy Where SONIC product policy disables settled commercial refunds, no public settled-refund route is exposed. A failed AI generation may **RELEASE** a temporary credit reservation. That is reservation reversal, not a commercial payment refund. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/errors-decimals-and-transactions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.