Error Handling

Directory uses coarse error categories modeled after DNS and HTTP. A sender either gets a route or it doesn’t. The error tells you why at the category level, not the implementation level.

Error Response Structure

{
  "status": 404,
  "code": "ADDRESS_NOT_FOUND",
  "message": "No address found for \"nobody\"",
  "field": "address"
}

Field	Type	Description
status	integer	HTTP status code
code	string	Machine-readable error code
message	string	Human-readable description
field	string	Which field caused the error (optional)

Error Codes

Code	Status	Meaning
INVALID_REQUEST	400	Request is malformed — missing address, bad JSON, wrong content type
ADDRESS_NOT_FOUND	404	No active address exists for the local part
UNSUPPORTED_PAIR	415	The DRS does not accept the requested value type / transfer type pair
PATHWAY_NOT_FOUND	404	Exchange node has no pathway to the requested output pair
INVALID_SIGNATURE	—	Client-side: contract signature failed verification
EXPIRED_CONTRACT	—	Client-side: contract TTL has elapsed
INTERNAL_ERROR	500	Unexpected server error
KV_UNAVAILABLE	503	Storage layer is unreachable

Design Rationale

DNS returns NXDOMAIN or an answer. HTTP returns a status code. Directory follows the same pattern. The protocol is a query and a response — it either resolves or it doesn’t. Complex error taxonomies belong in the operator’s implementation, not in the protocol.

Client Behavior

• 400 — fix the request. Check the field value.
• 404 — the address or pathway doesn’t exist. Don’t retry.
• 500 — server error. May retry with backoff.
• 503 — temporary unavailability. Retry after a delay.