# Error Reference \[Newton Protocol error codes, messages, and resolution steps]

This page documents all error codes and messages you may encounter when interacting with the Newton Protocol Gateway, SDK, and smart contracts.

## JSON-RPC Standard Errors

| Code | Message | Description |
|------|---------|-------------|
| -32700 | Parse error | Invalid JSON in request body |
| -32600 | Invalid request | Request does not conform to JSON-RPC 2.0 |
| -32601 | Method not found | Unknown RPC method name |
| -32602 | Invalid params | Missing or invalid method parameters |
| -32603 | Internal error | Unexpected server-side error |

## Newton-Specific Error Codes

| Code | Name | Description | Resolution |
|------|------|-------------|------------|
| -32615 | PolicyEvaluationError | Rego policy evaluation failed | Check Rego syntax, verify `data.wasm` and `data.params` are populated correctly |
| -32616 | ContractError | Smart contract interaction failed | Verify contract addresses are correct and contracts are deployed |
| -32617 | OperatorNotRegistered | Calling operator is not registered with the AVS | Ensure operator registration is complete |
| -32620 | DataProviderError | WASM oracle execution failed | Check WASM binary, verify secrets and `wasm_args` |

## Gateway Error Messages

| Error Message | Cause | Resolution |
|---------------|-------|------------|
| `"Unknown Newton RPC method: {method}"` | Typo in method name | Verify method spelling against [RPC API](/developers/reference/rpc-api) |
| `"Invalid request format: {details}"` | Malformed request parameters | Review parameter types and required fields |
| `"RpcRead permission required"` | API key lacks read permission | Use key with `rpc_read` or `rpc` permission |
| `"RpcWrite permission required"` | API key lacks write permission | Use key with `rpc_write` or `rpc` permission |
| `"Invalid API key"` | API key is invalid or expired | Verify key or create a new one via [Dashboard](/developers/overview/dashboard-api-keys) |
| `"policy_client is owned by another user"` | On-chain owner does not match API key holder | Use API key associated with the on-chain `getOwner()` address |
| `"policy client has no owner"` | Contract returned zero address for `getOwner()` | Verify contract is initialized with an owner |
| `"Missing secrets for N PolicyData contract(s)"` | Secrets not uploaded for PolicyData contracts | Upload secrets via `newt_storeEncryptedSecrets` |
| `"No secrets found for policy_client ... and policy_data..."` | No secrets stored for this client/data pair | Upload secrets or use `newt_simulatePolicyData` with inline secrets |
| `"Secrets upload validation failed: {details}"` | Secrets JSON does not match on-chain schema | Fix secrets format to match `secretsSchemaCid` schema |
| `"WASM execution failed: {details}"` | WASM oracle runtime error | Check WASM binary, inputs, and `wasm_args` |
| `"Rego evaluation failed: {details}"` | Policy syntax or runtime error | Fix Rego code, test with `newton-cli regorus eval` |
| `"Contract read failed: {details}"` | On-chain contract read failed | Verify contract addresses and chain connectivity |
| `"Task timeout"` | BLS aggregation exceeded timeout | Increase timeout parameter or retry |
| `"No operators available"` | No registered operators online | Retry later; check network status |
| `"TaskAlreadyExists"` | Duplicate task submission | Use a different nonce or wait for existing task |
| `"BlockNumberTooRecent"` | Reference block too close to current | Wait a few blocks before submitting |

## On-Chain Errors

| Error | Contract | Cause | Resolution |
|-------|----------|-------|------------|
| `InvalidAttestation()` | PolicyClient | BLS signature verification failed | Verify Task Manager address, check attestation expiration |
| `ExecutionFailed()` | PolicyClient | Inner transaction call reverted | Debug the target transaction independently |
| `PolicyClientNotRegistered` | PolicyClientRegistry | Client not registered or has been deactivated | Register via `registerClient()` or CLI: `newton-cli policy-client register`. See [PolicyClientRegistry](/developers/guides/smart-contract-integration#policyclientregistry) |
| `EmptyPolicySet` | PolicyClient | Empty replacement | Supply at least one spec |
| `TooManyPolicies` | PolicyClient | More than 8 policies in pinned release | Reduce the set size |
| `PolicyNotRegistered` | PolicyClient | Address not registered by configured factory | Verify TaskManager `policyFactory()` and factory `isPolicy` |
| `PolicyFactoryNotSet` | PolicyClient | Missing TaskManager or factory | Configure the correct deployment |
| `ZeroExpireAfter` | PolicyClient | A spec has zero expiry | Set a nonzero block window |
| `PolicyParamsTooLarge` | PolicyClient | Params exceed 65,536 bytes | Reduce encoded params |
| `OnlyPolicyClientOwner` | PolicyClient | Unauthorized replacement | Submit through the current owner |
| `PolicyDenied` | TaskManager | Aggregate decision is false | Inspect per-policy simulation results; do not execute |
| `Not authorized intent sender` | PolicyClient | `msg.sender` does not match `attestation.intent.from` | Ensure the user who signed the intent is the transaction sender |
| `Chain ID does not match` | PolicyClient | Attestation was created for a different chain | Verify the intent specifies the correct `chainId` |
| `Attestation expired` | TaskManager | `block.number >= attestation.expiration` | Request a new attestation; consider increasing `expireAfter` in policy config |
| `Attestation already spent` | TaskManager | Attestation has already been used | Each attestation is single-use; request a new one |
| `InterfaceNotSupported` | PolicyClient | Contract does not implement `IERC165` correctly | Override `supportsInterface` and call `super.supportsInterface(interfaceId)` |

### On-Chain Error Selectors

When `_validateAttestationDirect()` reverts, the error can originate from the PolicyClient, TaskManager, or AttestationValidator. Standard ABI decoders (including viem) may show "Unable to decode signature" because these selectors are not in your contract's ABI.

| Selector | Error | Meaning |
|----------|-------|---------|
| `0xec9758ff` | `InsufficientQuorumStake()` | Operators lack registered on-chain stake |
| `0x716dcc39` | `AttestationExpired()` | Attestation expired before tx was mined |
| `0x297fb567` | `AttestationHashMismatch()` | Task/response hash does not match attestation |
| `0x2a5d4fed` | `AttestationAlreadySpent()` | This attestation was already used |
| `0xf984c150` | `CertificateMessageHashMismatch()` | BLS certificate hash mismatch |
| `0x729d0f6b` | `SignatureVerificationFailed()` | BLS signature invalid |
| `0x90fe746d` | `ClientNotRegistered(address)` | Vault not in PolicyClientRegistry |

Use `cast sig "ErrorName()"` to compute selectors for new errors.

## SDK Error Codes

| Code | Description |
|------|-------------|
| `MISSING_API_KEY` | API key was not provided when initializing wallet client actions |
| `POPUP_ALREADY_EXISTS` | A Newton identity popup is already open |
| `MALFORMED_RESPONSE` | Gateway returned an unparseable response |
| `INVALID_ARGUMENT` | Invalid argument passed to an SDK method |
| `EXTENSION_NOT_INITIALIZED` | Client extension was not properly initialized |
| `INCOMPATIBLE_EXTENSIONS` | Conflicting client extensions detected |
| `FAILED_TO_OPEN_POPUP` | Browser blocked or failed to open the Newton popup |
| `FAILED_TO_RETRIEVE_NATIVE_TOKEN_BALANCE` | Could not read native token balance from the chain |

```ts twoslash
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { sepolia } from 'viem/chains';
import {
  newtonWalletClientActions,
  SDKError,
  SDKErrorCode,
} from '@newton-xyz/sdk';

const walletClient = createWalletClient({
  account: privateKeyToAccount('0x' + '1'.repeat(64) as `0x${string}`),
  chain: sepolia,
  transport: http('https://eth-sepolia.g.alchemy.com/v2/demo'),
}).extend(newtonWalletClientActions({ apiKey: 'test-api-key' }));

const request = {
  policyClient: '0x1234567890123456789012345678901234567890',
  intent: {
    from: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
    to: '0xb1aD5f82407bC0f19f42b2614fb9083035a36b69',
    value: '0x0',
    data: '0x',
    chainId: 11155111,
    functionSignature: '0x',
  },
  wasmArgs: ['0x'] as `0x${string}`[],
  timeout: 30,
} as const;
// ---cut---
try {
  await walletClient.evaluateIntentDirect(request);
} catch (error) {
  if (error instanceof SDKError) {
    switch (error.code) {
      case SDKErrorCode.MissingApiKey:
        // Provide an API key when initializing newtonWalletClientActions
        break;
      case SDKErrorCode.MalformedResponse:
        // Check gateway connectivity and API key validity
        break;
    }
  }
}
```

## HTTP Status Codes

| Status | Description |
|--------|-------------|
| 200 | Success (check JSON-RPC result for application-level errors) |
| 401 | Unauthorized — invalid API key |
| 403 | Forbidden — insufficient permissions |
| 429 | Too Many Requests — rate limited |
| 500 | Internal Server Error |
| 502 | Bad Gateway — service unavailable |

## Diagnostic Tools

* **`newton-cli regorus eval`** — test Rego policies locally with Newton crypto extensions
* **`newton-cli policy simulate`** — test full policy evaluation locally
* **`newton-cli policy-data simulate`** — test WASM oracle execution locally
* **`newt_simulatePolicy`** — test policy evaluation via the Gateway
* **`newt_simulatePolicyData`** — test WASM execution via the Gateway
* **[Newton Explorer](https://explorer.newton.xyz)** — view task status and evaluation results
* **[Explorer API](/developers/reference/explorer-api)** — script task and policy lookups with your API key