Error Codes

All errors follow a consistent format with machine-readable codes.

Error Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "violations": [...]  // Only for POLICY_DENIED
  }
}

MCP Errors

Code	HTTP	Description
`POLICY_DENIED`	200	Transaction violates one or more active policies. Includes violations array with policyId, policyType, and reason.
`TX_EXECUTION_FAILED`	200	On-chain transaction failed after policy approval (gas, revert, etc).
`INSUFFICIENT_BALANCE`	200	Agent wallet balance is less than the requested amount.
`MCP_AUTH_MISSING`	401	No Authorization header provided.
`MCP_AUTH_INVALID`	401	API key is invalid, revoked, or malformed.
`MCP_SCOPE_DENIED`	403	API key lacks the required scope (read/write) for this tool.
`RATE_LIMITED`	429	Too many requests. Check Retry-After header.
`WALLET_FROZEN`	200	The agent wallet has been frozen by the owner.

Note: Policy denials return HTTP 200 (not 403) so agents can read the structured error and react.

REST API Errors

Code	HTTP	Description
`AUTH_INVALID_CREDENTIALS`	401	Wrong email or password.
`AUTH_EMAIL_EXISTS`	409	Email already registered.
`AUTH_TOKEN_EXPIRED`	401	JWT has expired. Re-authenticate.
`WALLET_NOT_FOUND`	404	Agent wallet does not exist or belongs to another user.
`INVALID_AMOUNT`	400	Amount must be a positive number.
`INSUFFICIENT_MASTER_BALANCE`	400	Master wallet has insufficient funds for this transfer.
`KEY_NOT_FOUND`	404	API key does not exist or is already revoked.
`POLICY_NOT_FOUND`	404	Policy does not exist.
`TX_NOT_FOUND`	404	Transaction does not exist.
`TX_NOT_PENDING`	400	Transaction is not in pending state (already approved/rejected).
`NOT_FOUND`	404	Endpoint does not exist.
`VALIDATION_ERROR`	400	Request body failed Zod validation.

SDK Error Classes

The TypeScript SDK maps these codes to typed error classes:

Class	Code	Extra Fields
`PolicyDeniedError`	`POLICY_DENIED`	violations: PolicyViolation[]
`InsufficientBalanceError`	`INSUFFICIENT_BALANCE`	—
`ExecutionFailedError`	`TX_EXECUTION_FAILED`	txHash: string \| null
`AuthenticationError`	`AUTH_ERROR`	—
`RateLimitError`	`RATE_LIMITED`	retryAfter: number
`BithavenError`	`(any)`	Base class for all errors