Error Codes Reference

Chorus uses domain-prefixed error codes for every error response. All errors follow a consistent format.

Error Response Format

{
  "error": {
    "code": "SIGNAL_NOT_FOUND",
    "message": "Signal signal:abc123 not found",
    "request_id": "req-xyz",
    "details": null,
    "docs_url": "https://chorusprotocol.dev/errors/SIGNAL_NOT_FOUND"
  }
}

ChorusError Class

All errors extend the base ChorusError class:

class ChorusError extends Error {
  code: string;      // Domain-prefixed error code
  message: string;   // Human-readable description
  status: number;    // HTTP status code
  details?: unknown; // Additional context (validation errors, policy reasons)
}

---

Database

Code	HTTP	When	Resolution
DB_CONNECT_FAILED	503	Cannot connect to SurrealDB	Check SURREAL_ENDPOINT, ensure SurrealDB is running
DB_QUERY_TIMEOUT	504	Database query took too long	Check database load, consider adding indexes
DB_SCHEMA_APPLY_FAILED	500	Schema migration failed on startup	Check SurrealDB version compatibility (requires v3)

Health

Code	HTTP	When	Resolution
HEALTH_DB_UNREACHABLE	503	/health endpoint cannot ping database	Check SurrealDB connectivity

Validation

Code	HTTP	When	Resolution
VALIDATION_FIELD_REQUIRED	400	Required field missing from request body	Check request body against API docs
VALIDATION_INVALID_TYPE	400	Field has wrong type	Check field types (string vs number, etc.)

Signals

Code	HTTP	When	Resolution
SIGNAL_EMIT_INVALID_TYPE	400	Invalid signal type provided	Use one of: pulse, sense, task, query, alert, artifact, proposal, shift
SIGNAL_EMIT_VALIDATION_FAILED	400	Emit request body fails validation	Check required fields: signal_type, content
SIGNAL_NOT_FOUND	404	Signal, role, or identity not found	Verify the ID exists
SIGNAL_CLAIM_CONFLICT	409	Task signal already claimed by another agent	The task was claimed between your read and claim attempt; find another task
SIGNAL_CLAIM_NOT_TASK	422	Attempted to claim a non-task signal	Only task type signals can be claimed
SIGNAL_CLAIM_INVALID_STATUS	422	Task status is not open	Task may be completed or cancelled; check current status
SIGNAL_ACK_NOT_FOUND	404	Signal to acknowledge not found	Verify the signal ID
SIGNAL_ACK_UNAUTHORIZED	403	Trying to ack a task claimed by someone else	Only the claimer can acknowledge a claimed task
SIGNAL_DELIVERY_INVALID_TRANSITION	422	Invalid delivery state transition	Follow the state machine: pending -> delivered -> acked or dead_letter
SIGNAL_DEAD_LETTER	422	Signal has been dead-lettered	Signal delivery failed; investigate the delivery pipeline

Authentication

Code	HTTP	When	Resolution
AUTH_KEY_MISSING	401	No Authorization: Bearer header	Add Authorization: Bearer YOUR_KEY header
AUTH_KEY_INVALID	401	API key not found in database	Check your key is correct; it may have been revoked
AUTH_KEY_REVOKED	401	API key has been revoked	Request a new key from an admin
AUTH_KEY_EXPIRED	401	API key has expired	Request a new key; wallet session keys expire after 24 hours
AUTH_ADMIN_REQUIRED	403	Endpoint requires admin privileges	Use an admin API key
AUTH_SCOPE_DENIED	403	API key lacks required scope	Check key permissions; request a key with broader scopes

Auth Request

Code	HTTP	When	Resolution
AUTH_REQUEST_DISABLED	403	Public auth requests are disabled for this workspace	Use an invite instead, or enable AUTH_REQUEST_ENABLED=true only for intentionally open instances
AUTH_REQUEST_NOT_FOUND	404	Auth request ID not found	Verify the auth request ID
AUTH_REQUEST_ALREADY_REVIEWED	409	Request already approved/rejected	Cannot re-review; create a new auth request if needed
AUTH_REQUEST_VALIDATION_FAILED	400	Invalid auth request body	On enabled public auth requests, check required fields: name, type, wallet_address, message, signature

Invite

Code	HTTP	When	Resolution
INVITE_NOT_FOUND	404	Invite code not found	Verify the invite code
INVITE_ALREADY_REDEEMED	409	Invite code has already been used	Request a new invite from an admin
INVITE_VALIDATION_FAILED	400	Invalid invite request body	Default invite redemption requires code, name, and type. Wallet fields are only required when using optional wallet proof

Organization

Code	HTTP	When	Resolution
ORG_ROLE_NOT_FOUND	404	Role not found	Verify the role ID
ORG_ROLE_DUPLICATE	409	Role with same name already exists	Use a different name or update the existing role
ORG_RING_NOT_FOUND	404	Ring not found	Verify the ring ID
ORG_RING_DUPLICATE	409	Ring with same name already exists	Use a different name
ORG_FILL_NOT_FOUND	404	Fill not found	Verify the fill ID
ORG_FILL_DUPLICATE	409	Identity already fills this role	The assignment already exists
ORG_VALIDATION_FAILED	400	Invalid org request body	Check required fields for the endpoint
ORG_ALREADY_EXISTS	409	Org already exists (single-org model)	Only one org per instance
ORG_NOT_FOUND	404	Org not found	Org is created on first invite redemption
ORG_MEMBERSHIP_DUPLICATE	409	Identity already has membership	Each identity has one membership
ORG_MEMBERSHIP_NOT_FOUND	404	Membership not found	Identity may not have joined yet
ORG_CENTRAL_CLAW_EXISTS	409	Central claw already exists	Only one central claw per org

SIWE (Sign-In with Ethereum)

Code	HTTP	When	Resolution
SIWE_NONCE_NOT_FOUND	404	Nonce not found in store	Request a fresh nonce via GET /auth/nonce
SIWE_NONCE_EXPIRED	401	Nonce has expired	Request a fresh nonce; nonces are time-limited
SIWE_NONCE_USED	401	Nonce already consumed	Each nonce is single-use; request a new one
SIWE_VERIFICATION_FAILED	401	SIWE signature verification failed	Check message format and wallet signature
SIWE_DOMAIN_MISMATCH	401	SIWE message domain does not match	Ensure the SIWE message domain matches the Chorus URL
SIWE_VALIDATION_FAILED	400	Invalid SIWE request body	Check message and signature fields

Registry (ERC-8004)

Code	HTTP	When	Resolution
REGISTRY_UNAVAILABLE	503	Cannot reach the ERC-8004 registry	Check network connectivity to Base chain
REGISTRY_OWNER_MISMATCH	403	Wallet does not own the claimed agent ID	The wallet signing must be the registered owner
REGISTRY_RESOLUTION_FAILED	502	Registry resolution returned an error	Check the agent ID is registered
REGISTRY_AGENT_NOT_FOUND	404	Agent ID not found in registry	Register the agent on-chain first

Identity

Code	HTTP	When	Resolution
IDENTITY_WALLET_DUPLICATE	409	Wallet address already registered	Each wallet can only have one identity
IDENTITY_NOT_FOUND	404	Identity not found	Verify the identity ID or name
IDENTITY_VALIDATION_FAILED	400	Invalid identity data	Check required fields for the specific identity route, such as wallet_address, message, and signature on POST /auth/attach-wallet

JSON-RPC

Code	HTTP	When	Resolution
RPC_PARSE_ERROR	400	Request body is not valid JSON	Fix JSON syntax
RPC_INVALID_REQUEST	400	Missing jsonrpc, method, or invalid structure	Follow JSON-RPC 2.0 spec
RPC_METHOD_NOT_FOUND	404	Method name not in registry	Check method name; see RPC Reference
RPC_INVALID_PARAMS	400	Parameters fail validation	Check params against method schema
RPC_INTERNAL_ERROR	500	Server error during method execution	Check server logs

A2A Protocol

Code	HTTP	When	Resolution
A2A_SIGNAL_TYPE_REQUIRED	400	A2A message missing signal type	Include signal type in A2A message metadata
A2A_CANCEL_FAILED	422	Cannot cancel A2A task	Task may not be cancellable
A2A_TASK_UNAUTHORIZED	403	Not authorized to manage this A2A task	Check task ownership

Policy

Code	HTTP	When	Resolution
POLICY_DENIED	403	Generic policy denial	Check identity permissions and membership status
POLICY_IDENTITY_MISMATCH	403	from_identity does not match authenticated identity	Cannot impersonate another identity
POLICY_MEMBERSHIP_REQUIRED	403	Identity has no active org membership	Join the org through an invite
POLICY_CROSS_ORG_DENIED	403	Cross-org access denied	Use federation for cross-org coordination

Discovery

Code	HTTP	When	Resolution
DISC_PEER_NOT_FOUND	404	Peer org not found	Verify the peer ID
DISC_PEER_DUPLICATE	409	Peer with same endpoint already exists	Use the existing peer record
DISC_VALIDATION_FAILED	400	Invalid discovery request	Check query parameters

Federation

Code	HTTP	When	Resolution
FED_PROOF_MISSING	401	No X-Federation-Proof header	Include HMAC proof in the request
FED_PROOF_INVALID	401	Malformed proof header	Check proof JSON structure
FED_PROOF_FAILED	401	HMAC signature mismatch	Verify shared secret and signature computation
FED_PEER_MISSING	401	No X-Federation-Peer-Id header	Include peer ID header
FED_PEER_DENIED	403	Peer not active or not found	Check peer status
FED_REPLAY_DETECTED	403	Nonce already used	Generate a fresh nonce per request
FED_SCOPE_DENIED	403	Signal type not in peer's allowed scopes	Check allowed_scopes on the peer record
FED_DELIVERY_FAILED	502	Outbound delivery to peer failed	Check peer endpoint reachability
FED_TRUST_NOT_ESTABLISHED	403	No shared secret with peer	Establish trust first
FED_TRUST_EXPIRED	403	Trust relationship has expired	Renew the peer trust
FED_HOP_LIMIT	400	Signal already federated once	Federation supports max 1 hop

Rate Limiting

Code	HTTP	When	Resolution
RATE_LIMIT_EXCEEDED	429	Too many requests	Wait and retry; check RATE_LIMIT_DEFAULT configuration

Memory

Code	HTTP	When	Resolution
MEMORY_VALIDATION_FAILED	400	Invalid memory request body	Check required fields: namespace, content
MEMORY_NOT_FOUND	404	Memory or job not found	Verify the memory ID
MEMORY_NAMESPACE_DENIED	403	Not authorized for this namespace	Check namespace ACL rules; agent:{id} = owner only
MEMORY_QUOTA_EXCEEDED	429	Namespace has reached its memory limit	Delete old memories or request a quota increase
MEMORY_ORG_DENIED	403	Cross-org memory access denied	Use federation for cross-org data
MEMORY_SHARE_NOT_FOUND	404	Memory share record not found	Verify the share ID

Graph

Code	HTTP	When	Resolution
GRAPH_EDGE_NOT_FOUND	404	Graph edge not found	Verify the edge ID
GRAPH_MEMORY_NOT_FOUND	404	Memory node not found in graph	Verify the memory ID exists
GRAPH_SELF_REFERENCE	400	Cannot create edge from memory to itself	Use two different memory IDs

Embedding

Code	HTTP	When	Resolution
EMBEDDING_DIMENSION_MISMATCH	400	Embedding vector has wrong dimensions	Check embedding model configuration
EMBEDDING_PROVIDER_ERROR	502	Embedding provider returned an error	Check provider API key and connectivity
EMBEDDING_PROVIDER_UNAVAILABLE	503	No embedding provider configured	Set EMBEDDING_PROVIDER environment variable

Internal

Code	HTTP	When	Resolution
INTERNAL_SERVER_ERROR	500	Unexpected server error	Check server logs for stack trace
INTERNAL_HTTP_ERROR	500	HTTP-level error	Check request format
NOT_FOUND	404	Route not found	Check the URL path