Error Codes

Every error surfaced by the Notareum contracts and SDKs has a stable identifier. The identifier is the Solidity custom-error name on-chain and the equivalent typed error class in each SDK. This page groups the full error surface by category with cause, resolution, and the contract or SDK module that raises it.

Conventions

Contract errors are Solidity custom errors; they bubble up through the SDK as typed subclasses of NotareumError.
SDK-only errors (parsing, signature, transport) are typed SDK classes; they never touch the chain.
Every error carries a machine-readable code (uppercase_snake_case) that is stable across SDK versions.
Error codes in this page are grouped by category prefix: NOTA_PARSE_*, NOTA_SIG_*, REG_*, VER_*, STAKE_*, GOV_*, FEE_*.

Parsing errors (SDK)

Raised during ntm.nota.parse(raw) or ntm.nota.validate(nota).

`NOTA_PARSE_NOT_JSON`

Input is not valid JSON. Resolution. Confirm the payload is the full .nota content, not a truncated or base64-wrapped form. Use ntm.nota.decode(raw) first if the input is base64.

`NOTA_PARSE_UNSUPPORTED_VERSION`

Schema version is unknown to the SDK. Resolution. Upgrade the SDK to a version that supports the schema version in the file, or ask the issuer to produce a .nota with the currently supported schema.

`NOTA_PARSE_MISSING_FIELD`

Required field absent (resource, issuer, signature, or a sub-field of those). Resolution. The .nota was constructed incorrectly. Regenerate with the fluent builder, which enforces schema at build time.

`NOTA_PARSE_BAD_CHAIN`

chainId and chainName do not match the SDK’s canonical registry. Resolution. Use the SDK’s chainIdToName / chainNameToId helpers to produce the canonical pairing; do not hand-build these fields.

`NOTA_PARSE_IDENTIFIER_FORMAT`

identifier does not satisfy the format expected for the resource type and chain (e.g., an EVM address that is not 42 hex characters). Resolution. Normalize the identifier at creation; the builder’s validate() step catches this before signing.

Signature errors (SDK)

Raised by validate() during signature verification.

`NOTA_SIG_BAD_ALGORITHM`

Signature algorithm is not recognized or not valid for the resource’s chain family. Resolution. Use the SDK’s default signer helper; custom signers must declare the correct algorithm field (ecdsa-secp256k1, ed25519, schnorr-secp256k1).

`NOTA_SIG_VERIFY_FAILED`

Signature does not verify against the canonical serialization under the declared signer key. Resolution. Ensure the canonical serialization matches the signing implementation. Do not post-process the JSON between sign and ship. Use ntm.nota.canonicalize() explicitly if producing the payload externally.

`NOTA_SIG_EXPIRED`

The signature’s validFrom/validUntil window does not contain now. Resolution. Re-issue a fresh .nota. Payment requests and deposit addresses carry short validity windows for replay protection.

`NOTA_SIG_REVOKED_KEY`

The signing key has been revoked in the issuer’s DID document or via NotaRegistry. Resolution. Reject the .nota. Request a fresh one signed by a current key.

`NOTA_SIG_ISSUER_MISMATCH`

Recovered signer does not match any key declared for the issuer DID. Resolution. Verify the DID document and the declared signerKeyId. This error commonly indicates impersonation.

Registry errors (contract + SDK)

Raised by NotaRegistry calls.

`REG_ALREADY_REGISTERED`

A resource with the same (type, chainId, identifier) triple exists. Resolution. Use updateResource if the caller owns the existing record; otherwise, the identifier is taken and cannot be reused.

`REG_NOT_FOUND`

Resource ID does not map to any record. Resolution. Confirm the ID was computed correctly with computeResourceId. Confirm the resource has been registered on the correct network.

`REG_NOT_OWNER`

Caller is not the owner of the targeted resource. Resolution. The caller must hold the owner address recorded at registration, or transferOwnership must be performed by the current owner first.

`REG_ALIAS_TAKEN`

Alias is already bound to another, non-revoked resource. Resolution. Choose a different alias, or wait for the current owner to revoke and release.

`REG_INVALID_ALIAS`

Alias fails validation (length, allowed characters, reserved names). Resolution. Aliases must satisfy [a-z0-9.-]{1,63} after NFC/case normalization.

`REG_REVOKED`

The targeted resource is revoked. Resolution. Revoked resources are terminal for their ID; re-register with a different identifier or reach out to the owner.

`REG_PAUSED`

Registry operations are paused by PROTOCOL_ADMIN. Resolution. Wait for unpause (24-hour delay). For production integrations, subscribe to Paused / Unpaused events to gate user flows.

Verification errors (contract + SDK)

Raised by VerificationEngine.

`VER_ALREADY_OPEN`

A non-expired verification request exists for the resource. Resolution. Wait for the existing request to finalize or expire, then request again.

`VER_NOT_VALIDATOR`

Attester is not registered in ValidatorStaking or below Basic minimum. Resolution. Stake at least 10,000 NOTA to become an active validator. Use ntm.staking.isActive(addr) to confirm state.

`VER_TIER_TOO_LOW`

Validator’s tier is below the minimum for the target level (Professional for Enhanced, Enterprise for Institutional). Resolution. Increase stake to reach the required tier, or refrain from attesting requests above your eligible level.

`VER_DOUBLE_ATTEST`

Validator has already submitted an attestation for this requestId. Resolution. Attestations are single-shot per request; changes of mind are not supported within a round. File a dispute after finalization if the outcome is wrong.

`VER_DEADLINE_PASSED`

Request deadline has elapsed; no further attestations accepted. Resolution. The request will be finalized as expired or rejected. The requester can open a new request and will receive a partial fee refund.

`VER_DAILY_CAP`

Validator has exceeded their tier’s daily attestation cap. Resolution. Wait for the daily window to reset, or upgrade tier to increase the cap.

`VER_NOT_FINALIZABLE`

Quorum conditions are not met for finalizeRequest. Resolution. Poll request state; finalize only after attestCount >= required and the approval ratio threshold is met.

`VER_DISPUTE_WINDOW_CLOSED`

Attempted to open a dispute after the window expired. Resolution. Disputes must be opened within 24h (Basic), 48h (Enhanced), or 72h (Institutional) of finalization.

`VER_INVALID_BOND`

Dispute bond below the required amount for the request’s level. Resolution. Pay the exact bond returned by ntm.fee.quote(OpKind.DisputeBondX).

Staking errors (contract + SDK)

Raised by ValidatorStaking.

`STAKE_BELOW_MIN`

Resulting bonded stake would be below the Basic tier minimum (10,000 NOTA). Resolution. Stake at least the minimum; the contract rejects partial-registration attempts.

`STAKE_COOLDOWN_ACTIVE`

withdrawPending called before unstakeUnlockAt. Resolution. Wait for cooldown. The SDK exposes ntm.staking.getValidator(addr).unstakeUnlockAt to check.

`STAKE_NOTHING_TO_CLAIM`

claimRewards called with zero accrued rewards. Resolution. Accrue rewards by submitting attestations or staking-yield epochs before claiming.

`STAKE_FROZEN`

Validator is frozen by SlashingManager due to Collusion or Double-signing slash. Resolution. Wait for the freeze window (default 30 days). The freeze expiry is observable via isActive(addr) and associated events.

`STAKE_NO_ALLOWANCE`

NOTA allowance is insufficient for stake(amount). Resolution. approve NOTA to the staking contract, or use stakeWithPermit with an EIP-2612 signature.

Governance errors (contract + SDK)

Raised by veNOTA and AccessManager.

`GOV_LOCK_EXISTS`

createLock called while an active lock exists. Resolution. Use increaseLockAmount and/or extendLock to modify the existing lock; veNOTA is one-lock-per-address.

`GOV_LOCK_NOT_FOUND`

Modify or withdraw on a non-existent lock. Resolution. Create a lock first with createLock.

`GOV_LOCK_EXPIRED`

increaseLockAmount on an expired lock (no remaining voting power). Resolution. withdraw the expired lock and create a new lock with a fresh expiry.

`GOV_DURATION_OUT_OF_RANGE`

Lock duration below 1 week or above 4 years. Resolution. Choose a duration within [1 week, 4 * 365 days]. The SDK normalizes durations to the nearest weekly epoch.

`GOV_ROLE_DENIED`

AccessManager denied the call because the caller lacks the required role. Resolution. The function requires a specific role at the declared delay; only pre-authorized governance executors can call.

`GOV_DELAY_NOT_ELAPSED`

Scheduled operation executed before its eta. Resolution. Wait for the eta timestamp. Use schedule() correctly and record the operationId.

Fee errors (contract + SDK)

Raised by FeeManager.

`FEE_UNAUTHORIZED_CALLER`

Caller is not a pre-wired protocol contract (NotaRegistry, VerificationEngine, SlashingManager). Resolution. Only the protocol contracts invoke collect/refund; user code pays fees via those flows, not by calling FeeManager directly.

`FEE_INSUFFICIENT_PAYMENT`

NOTA balance + allowance below the quoted fee. Resolution. Approve at least ntm.fee.quote(op) in NOTA before the operation, or use the permit path.

`FEE_SPLIT_INVALID`

setSplit called with basis points that do not sum to 10000. Resolution. Governance proposal must set exactly 10000 bps across treasuryBps + burnBps + validatorPoolBps.

`FEE_EXCEEDS_CAP`

setFeeTable called with a fee above the absolute cap. Resolution. Adjust the proposal to stay within the governance-set caps. Caps are raised via separate proposals if needed.

`FEE_ZERO_ADDRESS`

setTreasury or setValidatorPool called with address(0). Resolution. Provide a non-zero destination. Burn-only flows use address(0xdead) by convention.

Error handling patterns

TypeScript

import { Notareum, NotareumError, RegistryError } from "@notareum/sdk";

try {
  await ntm.registry.registerResource(nota);
} catch (e) {
  if (e instanceof RegistryError && e.code === "REG_ALREADY_REGISTERED") {
    // update instead of register
  } else if (e instanceof NotareumError) {
    console.error(e.code, e.message);
  } else {
    throw e;
  }
}

Python

from notareum import Notareum
from notareum.errors import RegistryError, NotareumError

try:
    ntm.registry.register_resource(nota)
except RegistryError as e:
    if e.code == "REG_ALREADY_REGISTERED":
        ...
except NotareumError as e:
    log.error(e.code, e.message)

Rust

use notareum::{Notareum, SdkError};

match ntm.registry.register_resource(0u8, 1u64, identifier, &proof_hash, alias).await {
    Ok(tx) => { /* ... */ }
    Err(SdkError::Contract { reason, .. }) if reason == "REG_ALREADY_REGISTERED" => {
        /* update instead */
    }
    Err(e) => return Err(e.into()),
}

​Error Codes

​Conventions

​Parsing errors (SDK)

​NOTA_PARSE_NOT_JSON

​NOTA_PARSE_UNSUPPORTED_VERSION

​NOTA_PARSE_MISSING_FIELD

​NOTA_PARSE_BAD_CHAIN

​NOTA_PARSE_IDENTIFIER_FORMAT

​Signature errors (SDK)

​NOTA_SIG_BAD_ALGORITHM

​NOTA_SIG_VERIFY_FAILED

​NOTA_SIG_EXPIRED

​NOTA_SIG_REVOKED_KEY

​NOTA_SIG_ISSUER_MISMATCH

​Registry errors (contract + SDK)

​REG_ALREADY_REGISTERED

​REG_NOT_FOUND

​REG_NOT_OWNER

​REG_ALIAS_TAKEN

​REG_INVALID_ALIAS

​REG_REVOKED

​REG_PAUSED

​Verification errors (contract + SDK)

​VER_ALREADY_OPEN

​VER_NOT_VALIDATOR

​VER_TIER_TOO_LOW

​VER_DOUBLE_ATTEST

​VER_DEADLINE_PASSED

​VER_DAILY_CAP

​VER_NOT_FINALIZABLE

​VER_DISPUTE_WINDOW_CLOSED

​VER_INVALID_BOND

​Staking errors (contract + SDK)

​STAKE_BELOW_MIN

​STAKE_COOLDOWN_ACTIVE

​STAKE_NOTHING_TO_CLAIM

​STAKE_FROZEN

​STAKE_NO_ALLOWANCE

​Governance errors (contract + SDK)

​GOV_LOCK_EXISTS

​GOV_LOCK_NOT_FOUND

​GOV_LOCK_EXPIRED

​GOV_DURATION_OUT_OF_RANGE

​GOV_ROLE_DENIED

​GOV_DELAY_NOT_ELAPSED

​Fee errors (contract + SDK)

​FEE_UNAUTHORIZED_CALLER

​FEE_INSUFFICIENT_PAYMENT

​FEE_SPLIT_INVALID

​FEE_EXCEEDS_CAP

​FEE_ZERO_ADDRESS

​Error handling patterns

​TypeScript

​Python

​Rust

​Related pages