Errors

Error class hierarchy, Tokenomics 2.0 error families, 20 faucet codes, and on-chain revert names for the peaqOS SDK.

Every error raised by the SDK extends a common base, with one exception: a non-integer event value (and, for a Solana event in JS, timestamp or sourceChainId) raises the language’s own TypeError, not a PeaqosError. Faucet-specific codes are surfaced on the error instance (error.code) so callers can branch without string matching.

Class hierarchy

JavaScript

PeaqosError
├── ValidationError
├── RuntimeError
├── ValueCapExceeded
└── RateLimitExceeded

These four extend PeaqosError directly. Each function area adds its own family alongside them, also extending PeaqosError: MonetizationError (with MonetizationCompatibilityError), ProvisioningError, StreamError, OrchestrationError, and the Economics 2.0 family TokenomicsConfigError, TokenomicsActivationError (with its subclass TokenomicsPendingTransactionError), TokenomicsUnsupportedError, TokenomicsIntegrationUnavailableError (see Tokenomics 2.0 errors). McrApiError, a RuntimeError subclass, covers MCR query HTTP, transport and non-JSON failures; response shape and correlation failures are RuntimeError with code BAD_RESPONSE (see MCR API error codes). So err instanceof PeaqosError covers every SDK error; catching RuntimeError alone will miss ValueCapExceeded and RateLimitExceeded.

import {
  PeaqosError,         // base
  ValidationError,     // bad input
  RuntimeError,        // chain or HTTP failure; carries optional `code`
  ValueCapExceeded,    // operational cap hit (extends PeaqosError)
  RateLimitExceeded,   // operational cap hit (extends PeaqosError)
} from "@peaqos/peaq-os-sdk";

Python

PeaqosError
├── ValidationError
├── RpcError
├── ApiError
├── ValueCapExceeded
└── RateLimitExceeded

from peaq_os_sdk import (
    PeaqosError,
    ValidationError,
    RpcError,         # chain / web3 errors
    ApiError,         # HTTP API errors (faucet, MCR API)
    ValueCapExceeded,
    RateLimitExceeded,
)

Python separates transport-layer failures into RpcError (chain) and ApiError (faucet + MCR API). JavaScript collapses both into RuntimeError with a code field. The root also exports TokenomicsConfigError, TokenomicsActivationError, TokenomicsPendingTransactionError (a subclass of the activation error), TokenomicsUnsupportedError, TokenomicsIntegrationUnavailableError, and InputSizeError (a ValidationError subclass); peaq_os_sdk.monetization adds MonetizationCompatibilityError, MonetizationNetworkError, MonetizationResponseError, MonetizationTimeoutError, and MonetizationCancelledError. All extend PeaqosError. ApiError carries http_status, server_code, server_message, operation, home_protocol_chain_id, and retryable.

---

Tokenomics 2.0 errors

Raised by the Economics 2.0 surface: activation, machine management, and the 2.0 monetization client. Codes are string literals on err.code in both SDKs; the contract a revert came from travels on err.contract, and reverts are decoded by 4-byte selector scoped to that contract’s ABI. An unrecognised selector still surfaces as CONTRACT_REVERTED with the raw revertData / revert_data.

Class	Codes	Notes
TokenomicsConfigError	DEPLOYMENT_UNKNOWN, DEPLOYMENT_UNAVAILABLE, DEPLOYMENT_NOT_CONFIGURED, ADDRESS_OVERRIDE_MISMATCH (the CLI reports DEPLOYMENT_NOT_CONFIGURED as TOKENOMICS_NOT_CONFIGURED)	Deployment selection and address overrides. Agung monetization raises DEPLOYMENT_UNAVAILABLE, and so does a Solana call on a record without a Solana half (in JS also on a client with no Solana configuration); Python raises DEPLOYMENT_NOT_CONFIGURED for a Solana call with no Solana RPC endpoint. All before any read.
TokenomicsActivationError	Preflight: CHAIN_MISMATCH, CONTRACT_NOT_DEPLOYED, PEER_MISMATCH, SIGNER_UNAVAILABLE, NOT_ECONOMIC_AUTHORITY (the selected deployment’s MachineSubscription is not the economic authority), TECHNICALLY_PAUSED (activation and renewal read MachineStateAndSync.isTechnicalPausedGlobal() and isTechnicalPaused(machineId) before any approval; on Solana the quote reads the suite’s TechnicalPause account, the request, mint and link push read it before signing, and a settlement under a pause fails its pre-signing simulation; cancelling a request is not blocked by it; the on-chain TechnicallyPaused() revert and the Solana program error decode to the same code), INVALID_TIER, PRICE_NOT_AVAILABLE. Quote and funds: MACHINE_ID_MISMATCH, MAX_NET_PEAQ_EXCEEDED, MAX_USDT_EXCEEDED, INSUFFICIENT_BALANCE, APPROVAL_FAILED, ALLOWANCE_INSUFFICIENT, SLIPPAGE_EXCEEDED. Reads: MACHINE_NOT_FOUND, READ_FAILED. Management: NOT_OWNER_OR_CONTROLLER, NOT_MACHINE_OWNER, AUTHENTICATION_REWRITE_REQUIRED, MACHINE_RELOCATING, ERC721_INCORRECT_OWNER, ERC721_INSUFFICIENT_APPROVAL, ERC721_INVALID_APPROVER, ERC721_INVALID_OPERATOR. Submission: CONTRACT_REVERTED, EVENT_MISMATCH, STATE_MISMATCH, ABORTED, and a pending result when the receipt does not arrive: JS RECEIPT_UNAVAILABLE (peaq activation) or TRANSACTION_PENDING (management writes, and the Solana onboarding writes and registerSolanaOperator, as TokenomicsPendingTransactionError with .submitted), Python PENDING_TRANSACTION (as TokenomicsPendingTransactionError with .submitted). TIER_CHANGE_WHILE_ACTIVE (a renewal tier differs from the stored tier while the machine is Active; only on a deployment record that enables tier selection, so peaq-mainnet and agung-2026-08-28 raise RENEWAL_TIER_UNSUPPORTED instead), RENEWAL_TIER_UNSUPPORTED (a tier was passed but the deployment record does not enable tier selection; raised before any RPC), PEER_UNSET (InfoDesk has no address for a role the call needs), RPC_RATE_LIMITED (the peaq RPC kept rate-limiting reads after the retry budget; sends are never retried)	Attributes code, contract, operation, solidityError / solidity_error, revertData / revert_data, transactionHash / transaction_hash. Never resubmit after a pending or receipt-unavailable result; reconcile the hash. PEER_MISMATCH on machineBridgeAdapter, and a READ_FAILED that names fullMode(), both mean the installed SDK predates the current contracts; upgrade to the latest SDK.
TokenomicsUnsupportedError	LEGACY_REGISTRATION_UNSUPPORTED (registerMachine, mintNft, tokenIdOf), SPONSORED_ACTIVATION_UNSUPPORTED (registerFor, no replacement), MACHINE_RELOCATION_UNAVAILABLE (bridgeNft), SVM_APPROVAL_UNSUPPORTED, SVM_SAFE_TRANSFER_UNSUPPORTED (JS, approveMachine / safeTransferMachine once the machine resolves to Solana), SVM_APPROVAL_FOR_ALL_UNSUPPORTED (JS, setMachineApprovalForAll with chain: "solana"), SOLANA_OPERATION_UNSUPPORTED (Python, approve_machine / safe_transfer_machine; Python’s set_machine_approval_for_all stays an EVM write)	Deprecated or chain-incompatible entry points called in Tokenomics mode. Carries operation and replacement.
Solana-homed machines	TokenomicsActivationError: MACHINE_HOMED_ELSEWHERE (Python reads: the machine exists on another chain, named in the error), HOME_CHAIN_UNRESOLVED (JS reads, with homeChainState and homeChainReason), CHAIN_MISMATCH (machine not homed on the configured Solana deployment), TRANSACTION_PENDING (JS; Python: PENDING_TRANSACTION), EVENT_MISMATCH, STATE_MISMATCH (also a native signer or timestamp problem before broadcast), the terminal-first onboarding codes (registration CHAIN_NOT_REGISTERED, OPERATOR_BOUND_ELSEWHERE; quote and request TERMINAL_PAUSED, OPERATOR_NOT_REGISTERED, HOME_CHAIN_MISMATCH, REQUEST_ALREADY_OPEN, MACHINE_ALREADY_ACTIVE, ROUTE_NOT_WHITELISTED, PRICE_TOO_OLD, PRICE_TIMESTAMP_IN_FUTURE, TIER_NOT_PRICED, BOND_UNSIZEABLE, BOND_TOO_LARGE, ZERO_ESCROW_AMOUNT, ESCROW_BELOW_BOND, ESCROW_BALANCE_MISMATCH, INSUFFICIENT_BALANCE, NONCE_IN_USE, NONCE_NOT_MONOTONIC, NONCE_JUMP_TOO_LARGE, MACHINE_ID_TAKEN_ON_PEAQ; finalise and cancel REQUEST_NOT_COMMITTED, COMMIT_EXPIRED, NOT_ACTIVATION_PAYER, FINALISE_PATH_MISMATCH, FINALISE_TABLE_MISSING, FINALISE_TABLE_STALE, SWAP_ROUTE_MISCONFIGURED, TICK_ACCOUNTS_INVALID, UNSUPPORTED_TOKEN_PROGRAM, REQUEST_NOT_CANCELLABLE, REQUEST_NOT_YET_EXPIRED, REQUEST_CLOSED (SDK 0.11.2: the request was cancelled or refunded and its nonce is spent, so a phase run alone on it (the credit or bond wait, the settlement or its preview, the cancel) has nothing to do; run the request phase again and a new request opens at the next nonce); mint ACTIVATION_NOT_BONDED, ACTIVATION_REQUEST_MISMATCH, EVM_OPERATOR_MISMATCH) and the terminal results’ exit values REQUEST_EXPIRED and ACTIVATION_REFUNDED, the link push codes MACHINE_NOT_ONBOARDED, EVM_OPERATOR_UNSET, LINK_PUSH_TOO_LARGE, TV_OUTBOX_MISSING (the adapter has no Trust Validator outbox for peaq), TV_INBOUND_REFUSED (peaq refuses the node’s deliveries), and on a LayerZero route LINK_CONFIG_UNAVAILABLE, BRIDGING_DISABLED, LZ_SEND_LIBRARY_UNSUPPORTED and a ValidationError on max_link_push_fee_lamports / maxLinkPushFeeLamports when the cap is missing; a fee or rent over its ceiling is FEE_LIMIT_EXCEEDED / RENT_LIMIT_EXCEEDED in Python and SVM_FEE_EXCEEDED in JS, and a payer that cannot pay a write and keep its own rent-exempt minimum is INSUFFICIENT_NATIVE_BALANCE in Python (CLI: INSUFFICIENT_SOL) and INSUFFICIENT_BALANCE in JS, all raised before signing; a Solana read that a lagging server keeps refusing (-32016) is READ_FAILED naming the code (CLI: RPC_FAILED); and LINK_PUSH_UNSUPPORTED (TokenomicsConfigError, the deployment record names no LayerZero endpoint); a link push quote whose code is LINK_ALREADY_PUSHED is a result, not an error, and sends nothing, SUBSCRIPTION_NOT_ELIGIBLE (on the terminal reader, which the Solana half of peaq-mainnet (JS: solana-mainnet) uses: the mint needs a SubscriptionTerminal that peaq has sequenced (last_seq not 0) in status Active, Grace or Runoff, and an event needs status Active or Grace; the CLI maps it to exit 1), and in JS the native budget codes SVM_FEE_EXCEEDED, SVM_COMPUTE_EXCEEDED, SVM_TRANSACTION_TOO_LARGE. TokenomicsConfigError: SVM_PACKAGE_MISSING (JS: @solana/web3.js or @coral-xyz/anchor not installed), DEPLOYMENT_UNAVAILABLE (no Solana RPC configured, or a deployment without a Solana half), and in JS the deployment-record checks SVM_PACKAGE_UNUSABLE, SVM_CLUSTER_MISMATCH, SVM_PROGRAM_NOT_DEPLOYED, SVM_ACCOUNT_OWNER_MISMATCH, SVM_PEER_MISMATCH before the first account read. ValidationError subclass InputSizeError (Python) for oversized DID or credential input. MCR queries: McrApiError (JS) / ApiError (Python) with INVALID_REQUEST, UNAUTHORIZED, NOT_FOUND, MACHINE_HOMED_ELSEWHERE, CONFLICT, SERVICE_UNAVAILABLE and the server’s own code on serverCode / server_code. Monetization refusals before anything is sent: UNSUPPORTED_HOME_CHAIN, SIGNER_INCOMPATIBLE_WITH_HOME, SOLANA_MONETIZATION_UNVERIFIED, SIGNER_NOT_NATIVE_OWNER, AUTHORIZATION_CONTEXT_CHANGED, INVALID_SIGNER_OUTPUT	Solana management writes report rather than raise once a transaction landed. Python: status is confirmed, conflicting, failed or pending, plus expired from reconciliation, the only status with may_resubmit=True. JS: confirmed, unconfirmed, blocked or failed; unconfirmed may have landed and is reconciled, never replaced. NOT_FULL_MODE is still exported but no longer raised by the activation preflight, which reads isEconomicAuthority(). See SDK JS: Solana, SDK Python: Solana.
Lifecycle and pool codes (both SDKs)	TokenomicsActivationError: ALREADY_ACTIVATED, NOT_ACTIVATED, ALREADY_TERMINATED, NOT_ACTIVE, NOT_SUSPENDED, PROVISION_POOL_NOT_CONFIGURED, INSUFFICIENT_RESERVE, INSUFFICIENT_USDT_RECEIVED; Python also DRY_RUN_UNSUPPORTED	Decoded reverts from MachineStateAndSync, MachineSubscription and the provision pool. Not retryable: fix the state or the configuration
TokenomicsIntegrationUnavailableError	TOKENOMICS_INTEGRATION_UNAVAILABLE	Carries integration (legacy DID helpers or orchestration identity binding) and owningTicket / owning_ticket. Raised before any HTTP, RPC, or signing.
MonetizationCompatibilityError	MONETIZATION_API_INCOMPATIBLE	The 2.0 MCR’s /.well-known/peaq-monetization signal is missing or does not match the deployment. mcr.peaq.xyz publishes the signal; the error means its protocol version, chain ID, or MachineRegistry address does not match the selected deployment.
MonetizationApiError (JS) / MonetizationError (Python)	Server codes from the PUT endpoint page, including MACHINE_UNAVAILABLE (503, the only retryable code) and CHAIN_UNAVAILABLE	Branch on code, never on the message. Timeouts and cancellations are separate classes: Python MonetizationTimeoutError (MONETIZATION_TIMEOUT) and MonetizationCancelledError (MONETIZATION_CANCELLED); JS MonetizationTimeoutError and MonetizationCancellationError, which carry no code.

Error messages pass through credential redaction (URL userinfo, secret query parameters, 32-byte hex). Revert data and transaction hashes are kept unredacted on the attributes.

---

Faucet error codes

All 20 codes the Gas Station can return. POST /faucet/fund, POST /2fa/setup, and POST /2fa/confirm each return a subset. For example, QR_GENERATION_FAILED only comes from /2fa/setup. QR_NOT_FOUND and QR_EXPIRED come from GET /2fa/qr/{token} when you open the qrImageUrl, so they reach your HTTP client, not an SDK error. Codes surface as RuntimeError.code (JS) or ApiError.code (Python).

2FA errors

Code	Description	Retry
INVALID_2FA	OTP rejected by the faucet	Yes: submit a fresh 6-digit code
2FA_NOT_CONFIGURED	Owner has not completed setup_faucet_2fa	No: re-run setup
2FA_NOT_ACTIVE	2FA enrolled but not confirmed	No: call confirm_faucet_2fa with a valid OTP
2FA_LOCKED	Too many invalid attempts; owner temporarily blocked	After lockout window

Idempotency errors

Code	Description	Retry
DUPLICATE_REQUEST	Same request_id already in flight	No: use a different request_id or wait for prior result
REQUEST_ALREADY_PROCESSED	Same request_id already resolved	No: read the prior result

Rate limit & cap errors

Code	Description	Retry
RATE_LIMITED	Faucet rate limit exceeded	After cooldown
CAP_EXCEEDED_OWNER	Daily per-owner funding cap reached	Next day
CAP_EXCEEDED_WALLET	Daily per-target-wallet cap reached	Next day, or target a different wallet

Validation errors

Code	Description	Retry
INVALID_PAYLOAD	Request body malformed	No: fix the payload
INVALID_OWNER_ADDRESS	owner_address not a recognized format	No
INVALID_TARGET_ADDRESS	target_wallet_address not recognized	No
INVALID_CHAIN_ID	chain_id not configured on the faucet	No
INVALID_REQUEST_ID	request_id not a UUID	No

Chain & server errors

Code	Description	Retry
TRANSFER_FAILED	On-chain transfer reverted or stalled	Yes
CHAIN_RPC_ERROR	Faucet’s RPC call failed	Yes
INTERNAL_ERROR	Faucet internal failure	Yes

QR errors

Code	Description	Retry
QR_NOT_FOUND	QR image expired or never created	No: re-run setup
QR_EXPIRED	QR retrieval attempted after ~2 min TTL	No: re-run setup
QR_GENERATION_FAILED	Faucet could not generate the image	Yes

Full flow reference: Gas Station concept, setupFaucet2FA, fund_from_gas_station.

---

On-chain revert names (Tokenomics 1.0)

These are the IdentityRegistry, IdentityStaking, MachineNFT, and EventRegistry reverts. Economics 2.0 reverts are decoded per contract into the TokenomicsActivationError codes above. Revert names the SDK translates to a friendly message and surfaces as RuntimeError.code (JS) or RpcError.code (Python). The contracts define more custom errors than this table; anything not listed surfaces as code: "TX_REVERTED" (Python) or code: "<RawErrorName>" with a generic Transaction reverted: … message (JS, when viem decodes the selector).

Revert	Raised by	Cause
AlreadyRegistered	registerMachine / registerFor / register_machine	Address already has a machine ID
InvalidMachineAddress	registerFor	machineAddress is the zero address
InvalidAddress	Staking / NFT flows	Caller passed the zero address where a real address is required
AmountZero	Staking / bond flow	Bond amount is zero
AlreadyStaked	Staking flow	Machine is already bonded/staked
MachineNotBonded	mintNft / mint_nft	Caller’s machine is not bonded on the IdentityRegistry
AlreadyMinted	mintNft / mint_nft	An NFT is already minted for the machine
NotMachineOwner	mintNft / mint_nft	Caller is not the owner of the machine
RecipientMustBeMachineOwner	mint_nft (Python)	Operator-mint guard: recipient must be the registered machine owner. Python-only: the JS SDK surfaces this revert as code: "<RawErrorName>" via the viem decode path.
MachineNotFound	submitEvent / tokenIdOf	machineId has no Identity record on the IdentityRegistry
MachineDeactivated	submitEvent	The machine has been deactivated by the IdentityRegistry
NotAuthorizedSubmitter	submitEvent	Caller is not authorized to submit events for this machine
InvalidEventType	submitEvent	eventType is not 0 (revenue) or 1 (activity)
InvalidTrustLevel	submitEvent	trustLevel is not 0, 1, or 2

MCR API error codes

Returned by queryMcr / query_mcr, queryMachine / query_machine, and queryOperatorMachines / query_operator_machines against the deployment’s MCR server (mcr.peaq.xyz); the helpers need a tokenomics20 client. In JS, HTTP, transport and non-JSON failures throw McrApiError (a RuntimeError subclass) with these codes, and response shape and correlation failures (a malformed or non-canonical machine_id, a response about a different machine or operator than requested, a null or non-integer mcr_score) throw RuntimeError with code BAD_RESPONSE. In Python every one of these failures is ApiError with the same codes. Both SDKs carry the server’s own code on serverCode / server_code plus httpStatus / http_status, homeProtocolChainId / home_protocol_chain_id and retryable (a classification only; the transport never retries). The constants are MCR_HTTP_ERROR_CODE in both SDKs.

Code	Cause	Retry
INVALID_REQUEST	HTTP 400, for example an address-form DID sent to mcr.peaq.xyz	No: check the input
UNAUTHORIZED	HTTP 401 or 403	No
NOT_FOUND	The DID, machine, or token ID was not found by the MCR API (HTTP 404)	No: check the input
MACHINE_HOMED_ELSEWHERE	HTTP 409 with that server code: the machine exists but the server could not read its home chain; home_protocol_chain_id names it. Per the 2.0 server’s contract	No: not absence, do not retry as NOT_FOUND
CONFLICT	Any other HTTP 409	No
BAD_RESPONSE	The MCR returned a non-JSON body or an unexpected payload shape	No: file an issue if it persists
HTTP_ERROR	The MCR returned a non-2xx status other than 400, 401, 403, 404, 409, 503 and 5xx	Maybe: surface the status code and decide
SERVER_ERROR	The MCR returned a 5xx other than 503. retryable: false in both SDKs	Maybe: the reads are GETs, so one retry with backoff is safe
SERVICE_UNAVAILABLE	The MCR returned 503 (Service not initialised / Chain unavailable; per the 2.0 server’s contract also a Solana-homed machine that is relocating or whose home chain is unreachable). retryable: true (in both SDKs TIMEOUT and NETWORK_ERROR are retryable too)	Yes, with backoff
TIMEOUT	The HTTP request exceeded timeoutMs	Yes
NETWORK_ERROR	Transport-level failure (DNS, TCP, TLS)	Yes
ABORTED	The caller aborted the request via AbortSignal (JS only)	Caller’s choice

Verify errors

Raised by the experimental Verify surface (@peaqos/peaq-os-sdk/verify, peaq_os_sdk.verify). All extend VerifyError, a PeaqosError; the typed fields carry the outcome and the messages hold no server text, URLs or identifiers. Full tables in SDK JS: Verify and SDK Python: Verify.

Class	Raised by	Cause
VerifyConfigError	read client	Invalid API origin or options, or the client is closed. Before any request
VerifyValidationError	read client	machineId is not a decimal in 1..2^256-1, or bad request options. Before any request
VerifyIdentityError	read client	404 MACHINE_NOT_FOUND: reason: "machine-not-found" in JS, subclass VerifyMachineNotFoundError in Python. The only error that means there is no machine with this ID in the Verify service
VerifyRateLimitError	read client	429; retryAfterSeconds / retry_after_seconds is 1..60 or unset. Never retried by the SDK
VerifyTransportError	read client	Timeout, cancellation, network failure, 500/503 (causeCategory / cause_category "unavailable") or another documented HTTP error ("http-status")
VerifyProtocolError	read client	Malformed, oversized or undocumented response, including 401/403. Not a verification state
VerifyCryptographicError	chip preflight	Certificate is not a valid CA306 leaf, does not chain to the trust bundle or is not the supported profile; chip or controller signature does not match this attempt
VerifyEvidenceError	chip preflight	Evidence document breaks its schema, exceeds its size limit, could not be canonicalized, or a derived value was zero
VerifyFreshnessError	chip preflight	Challenge outside its five-minute window

OWS signing error codes

Raised when transaction signing routes through an OWS vault wallet (PeaqosClient.fromWallet / from_wallet with owsSigning=true). The SDK normalises the upstream OWS error code into a typed SDK exception. Only INVALID_INPUT becomes ValidationError(field="transaction"); the other four become a plain PeaqosError in both SDKs. Python sets the OWS code on err.code and chains the raw error as __cause__; JS keeps the raw error on err.cause and sets no code.

Code	Cause	Surfaces as
WALLET_NOT_FOUND	Vault wallet name / UUID does not exist	PeaqosError (err.code in Python)
INVALID_PASSPHRASE	Wrong vault passphrase	PeaqosError (err.code in Python)
INVALID_INPUT	Malformed transaction or sign-hash payload	ValidationError(field="transaction")
POLICY_DENIED	Signing blocked by an OWS policy rule	PeaqosError (err.code in Python)
CHAIN_NOT_SUPPORTED	Transaction chainId is not configured in OWS	PeaqosError (err.code in Python)

Constants exported from the JS SDK root and from peaq_os_sdk.constants in Python as OWS_ERROR_WALLET_NOT_FOUND, OWS_ERROR_INVALID_PASSPHRASE, OWS_ERROR_INVALID_INPUT, OWS_ERROR_POLICY_DENIED, OWS_ERROR_CHAIN_NOT_SUPPORTED. JS additionally exports the OwsSigningErrorCode union type.

In JS SDK 0.10.0 an OWS signing failure surfaces as a PeaqosError with no code, and err.cause.code is the native binding’s "GenericFailure", so the OWS codes cannot be branched on in JS yet; log err.message instead. In Python, branch on err.code:

from peaq_os_sdk import PeaqosError
from peaq_os_sdk.constants import (
    OWS_ERROR_INVALID_PASSPHRASE,
    OWS_ERROR_CHAIN_NOT_SUPPORTED,
)

try:
    client.activate_machine(...)  # any signed write
except PeaqosError as err:
    if err.code == OWS_ERROR_INVALID_PASSPHRASE:
        ...  # prompt re-auth
    if err.code == OWS_ERROR_CHAIN_NOT_SUPPORTED:
        ...  # OWS chain config bug
    raise

SDK transaction sentinels

Raised by the SDK’s transaction helper around any contract call. Surfaced as RuntimeError.code (JS) or RpcError.code (Python).

Code	Cause
WALLET_NOT_CONFIGURED	Method requires a signer but none was configured. (JS only. In Python, a client built without an OWS signer needs private_key unless it is a tokenomics20 client with creation_home="solana"; otherwise construction raises ValidationError. A write without a signer raises TokenomicsActivationError SIGNER_UNAVAILABLE.)
TX_REVERTED	The transaction reverted on-chain. The revert reason is in the message; revert names from the table above are decoded into code when the SDK recognizes them.
RECEIPT_AWAIT_FAILED	Transaction was submitted but the SDK could not retrieve a receipt. The tx may still have landed; re-query by hash before retrying.
REGISTERED_EVENT_MISSING	Receipt has no Registered event log. Indicates a contract/SDK ABI mismatch.
REGISTERED_EVENT_MALFORMED	Registered event log was decoded but had unexpected fields. Same root cause as above.
INVALID_FEE_RESULT	quoteSend on the LayerZero ONFT adapter returned a malformed MessagingFee. Raised inside bridge_nft (Python) before submission.

Faucet / HTTP envelope sentinels

Raised by the SDK when a faucet or MCR response is reachable but unparseable. Surfaced as ApiError.code (Python). The JS SDK collapses these into the generic RuntimeError envelope path.

Code	Cause
INVALID_RESPONSE	Faucet returned a non-JSON body.
UNEXPECTED_RESPONSE	Faucet returned JSON but the status / code / data envelope did not match the expected shape for the endpoint.
NETWORK_ERROR	Transport-level failure during a faucet call (DNS, connection refused, TLS, timeout via requests.RequestException). Same sentinel as the MCR API table above.

Client-side error codes

Raised by the SDK itself (not by a chain revert). Surfaced as RuntimeError.code (JS) or ValidationError/RpcError attributes (Python).

Code	Raised by	Cause
MIN_BOND_INVALID_RESULT	registerMachine / registerFor (JS only)	IdentityRegistry.minBond() returned a non-bigint value before submitting the bond.

---

Error handling patterns

JavaScript

import {
  PeaqosError,
  ValidationError,
  RuntimeError,
  RateLimitExceeded,
} from "@peaqos/peaq-os-sdk";

try {
  await client.fundFromGasStation(params, faucetUrl);
} catch (err) {
  if (err instanceof ValidationError) {
    // fix caller input
  } else if (err instanceof RateLimitExceeded) {
    // back off
  } else if (err instanceof RuntimeError) {
    switch (err.code) {
      case "INVALID_2FA":
        // prompt for a fresh TOTP
        break;
      case "CAP_EXCEEDED_OWNER":
      case "CAP_EXCEEDED_WALLET":
        // surface cap messaging
        break;
      default:
        throw err;
    }
  } else {
    throw err;
  }
}

Python

from peaq_os_sdk import PeaqosError, ValidationError, ApiError, RpcError

try:
    client.fund_from_gas_station(
        owner_address=owner,
        target_wallet_address=target,
        chain_id="peaq",
        two_factor_code=totp,
        faucet_base_url=faucet_url,
    )
except ValidationError:
    # fix caller input
    raise
except ApiError as err:
    if err.code == "INVALID_2FA":
        # prompt for a fresh TOTP
        pass
    elif err.code in ("CAP_EXCEEDED_OWNER", "CAP_EXCEEDED_WALLET"):
        # surface cap messaging
        pass
    else:
        raise
except RpcError:
    # retry with backoff
    raise

---

Related

• SDK JS
• SDK Python
• Gas Station concept
• Install page troubleshooting