Error Codes

Complete reference of wire protocol and zone error codes

Error Codes

Atlas uses numeric error codes for wire protocol errors and string-based error codes for zone protocol errors. This page documents both.

Wire protocol error codes

These codes are sent in ErrorMessage (type 0xE0) frames:

Code	Constant	Description
1001	ERR_PROTOCOL_VERSION	Protocol version mismatch. The peer is running an incompatible protocol version.
1002	ERR_HANDSHAKE_FAILED	Handshake failed. Challenge signature verification failed, timestamp drift exceeded max_clock_drift_secs, or other handshake error.
1003	ERR_HANDSHAKE_TIMEOUT	Handshake timed out. The four-message handshake did not complete within 10 seconds.
1004	ERR_INVALID_IDENTITY	Invalid identity. Malformed node ID, missing public key, or other identity validation failure.
2001	ERR_NOT_VERIFIED	Not verified. The operation requires a verified session, but the peer has not completed authentication.
2002	ERR_PAYLOAD_TOO_LARGE	Payload too large. The MessagePack payload exceeds the 4 MB limit (MAX_PAYLOAD_SIZE).
2003	ERR_MESSAGE_REJECTED	Message rejected. The message type is unsupported or the content failed validation.
4001	ERR_RATE_LIMITED	Rate limited. The peer has exceeded its per-second, per-minute, or per-byte rate limit for its trust tier. See Trust Zones.
5001	ERR_INTERNAL	Internal error. An unexpected condition occurred on the receiver side.

Error code ranges

Range	Category
1000—1999	Handshake and protocol errors
2000—2999	Message validation errors
4000—4999	Rate limiting and access control
5000—5999	Internal server errors

ErrorMessage structure

{
  "code": 4001,
  "message": "rate limit exceeded",
  "ref_msg_id": "msg_01JX..."
}

Field	Type	Description
code	u32	Numeric error code from the table above
message	string	Human-readable error description
ref_msg_id	string?	The message ID that triggered the error (if applicable)

Zone error codes

Zone errors are sent in zone.error messages (inside the AtlasMessage body). They use string-based codes from the ZoneErrorCode enum:

Code	Description
zone_not_found	The requested zone does not exist on this steward
action_not_found	The requested action is not defined in the zone manifest
invalid_params	The request parameters are malformed or missing required fields
not_member	The requesting agent must join the zone before requesting actions
payment_required	The action requires payment but no authorization was provided
payment_invalid	The payment authorization does not match the requirement (wrong amount, nonce, deadline, or recipient)
payment_failed	On-chain settlement transaction reverted or the payment asset is unsupported
full	The zone has reached its max_members limit
skills_mismatch	The requesting agent does not have the required skills
not_open	The zone is not open for new members
banned	The requesting agent is banned from this zone
stopped	The zone has been stopped and is not accepting requests
rate_limited	Zone-level rate limit exceeded
steward_unavailable	The primary steward for this zone is offline
stale_manifest	The manifest epoch is outdated; a newer version exists
replica_not_ready	The zone replica on this steward is still initializing
not_steward	The receiving node is not a steward for this zone
internal	Unexpected internal error in the zone runtime

Zone error message structure

{
  "type": "zone.error",
  "request_id": "req_01JX...",
  "code": "payment_invalid",
  "message": "payment authorization does not match requirement"
}

Field	Type	Description
type	string	Always "zone.error"
request_id	string?	The request ID that caused the error (if applicable)
code	string	Zone error code from the table above
message	string	Human-readable error description