Errors - peaq

Every error raised by the extends a common base. Faucet-specific codes are surfaced on the error instance (error.code) so callers can branch without string matching.

Class hierarchy

JavaScript
Python

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

These four extend PeaqosError directly. Each function area adds its own family alongside them, also extending PeaqosError: MonetizationError (plus MonetizationCompatibilityError since 0.6.0), ProvisioningError, StreamError, OrchestrationError, and since 0.6.0 the Economics 2.0 family TokenomicsConfigError, TokenomicsActivationError, TokenomicsUnsupportedError, TokenomicsIntegrationUnavailableError (see Tokenomics 2.0 errors). So catch (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";

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. Since 0.6.0 the root also exports TokenomicsConfigError, TokenomicsActivationError, TokenomicsPendingTransactionError (a subclass of the activation error), TokenomicsUnsupportedError, and TokenomicsIntegrationUnavailableError; peaq_os_sdk.monetization adds MonetizationCompatibilityError, MonetizationNetworkError, MonetizationResponseError, MonetizationTimeoutError, and MonetizationCancelledError. All extend PeaqosError.

Tokenomics 2.0 errors

Raised by the Economics 2.0 surface (SDK 0.6.0+): 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 the never-merged address overrides. Agung monetization raises `DEPLOYMENT_UNAVAILABLE`.
`TokenomicsActivationError`	Preflight: `CHAIN_MISMATCH`, `CONTRACT_NOT_DEPLOYED`, `PEER_MISMATCH`, `SIGNER_UNAVAILABLE`, `NOT_FULL_MODE`, `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` (activation) or `TRANSACTION_PENDING` (management writes), Python `PENDING_TRANSACTION` (as `TokenomicsPendingTransactionError` with `.submitted`)	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` against `peaq-mainnet` means an SDK older than `@peaqos/peaq-os-sdk` 0.7.0 / `peaq-os-sdk` 0.7.1 (the adapter was re-pointed on 2026-09-08); upgrade.
`TokenomicsUnsupportedError`	`LEGACY_REGISTRATION_UNSUPPORTED` (`registerMachine`, `mintNft`, `tokenIdOf`), `SPONSORED_ACTIVATION_UNSUPPORTED` (`registerFor`, no replacement), `MACHINE_RELOCATION_UNAVAILABLE` (`bridgeNft`)	Deprecated entry points called in Tokenomics mode. Carries `operation` and `replacement`.
`TokenomicsIntegrationUnavailableError`	`TOKENOMICS_INTEGRATION_UNAVAILABLE`	Carries `integration` (`legacy DID helpers`, `orchestration identity binding`; `events` and `MCR/query` were removed in JS 0.7.0 / Python 0.7.1, which enable both in Tokenomics mode) 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-20.peaq.xyz` publishes the signal since 2026-09-05; you still see this against a self-hosted MCR that has not been upgraded, or when `TOKENOMICS_DEPLOYMENT_ID` names a different chain than the host serves.
`MonetizationApiError` (JS) / `MonetizationError` (Python)	Adds `MACHINE_UNAVAILABLE` (503, the only retryable code) and `CHAIN_UNAVAILABLE` to the 1.0 table	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 can return from POST /faucet/fund, POST /2fa/setup, and POST /2fa/confirm. Each endpoint returns a subset. For example, INVALID_OWNER_ADDRESS and QR_GENERATION_FAILED only come from /2fa/setup. 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`	Per-IP or per-wallet throttle hit	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. 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 MCR API: mcr.peaq.xyz in legacy mode, the deployment’s 2.0 server (mcr-20.peaq.xyz) in Tokenomics mode since JS 0.7.0 / Python 0.7.1. Surfaced as RuntimeError.code (JS) or ApiError.code (Python). In Tokenomics mode a malformed or non-canonical machine_id, or a response about a different machine or operator than requested, is BAD_RESPONSE.

Code	Cause	Retry
`NOT_FOUND`	The DID, machine, or token ID was not found by the MCR API (HTTP 404)	No: check the input
`BAD_RESPONSE`	The MCR returned an unexpected payload shape	No: file an issue if it persists
`HTTP_ERROR`	The MCR returned an unhandled non-2xx status	Maybe: surface the status code and decide
`SERVER_ERROR`	The MCR returned 5xx	Yes, with backoff
`SERVICE_UNAVAILABLE`	The MCR returned 503 (`Service not initialised` / `Chain unavailable`)	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

OWS signing error codes

Raised when routes through an (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; the other four become PeaqosError (or RuntimeError in JS) with the original OWS error preserved as .cause.

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

Constants exported from both SDKs 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.

import { OWS_ERROR_INVALID_PASSPHRASE, OWS_ERROR_CHAIN_NOT_SUPPORTED } from "@peaqos/peaq-os-sdk";

try {
  await client.bridgeNft({ tokenId, destination: "base" });
} catch (err) {
  if (err.cause?.code === OWS_ERROR_INVALID_PASSPHRASE) { /* prompt re-auth */ }
  if (err.cause?.code === OWS_ERROR_CHAIN_NOT_SUPPORTED) { /* OWS chain config bug */ }
  throw err;
}

from peaq_os_sdk import (
    OWS_ERROR_INVALID_PASSPHRASE,
    OWS_ERROR_CHAIN_NOT_SUPPORTED,
    PeaqosError,
)

try:
    client.bridge_nft(token_id=..., destination="base")
except PeaqosError as err:
    code = getattr(err.__cause__, "code", None)
    if code == OWS_ERROR_INVALID_PASSPHRASE:
        ...  # prompt re-auth
    if 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; the Python `PeaqosClient` constructor requires a `private_key` and surfaces this as `ValidationError`.)
`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
Python

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;
  }
}

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

​Class hierarchy

​Tokenomics 2.0 errors

​Faucet error codes

​On-chain revert names (Tokenomics 1.0)

​MCR API error codes

​OWS signing error codes

​SDK transaction sentinels

​Faucet / HTTP envelope sentinels

​Client-side error codes

​Error handling patterns

​Related