Error format

z4j errors follow RFC 7807 Problem Details.

Shape

{
  "type": "https://z4j.dev/errors/validation",
  "title": "validation failed",
  "status": 422,
  "detail": "email is not a valid email address",
  "code": "invalid_email",
  "instance": "/api/v1/memberships/invite",
  "errors": [
    { "field": "email", "code": "invalid_email", "message": "not a valid email address" }
  ]
}

• type - stable URL identifier. Group clients by type.
• code - stable short identifier for programmatic branching.
• errors - per-field breakdown when the top-level is a validation failure.

HTTP status reference

Status	When
400	Bad request (malformed JSON, bad query parameter)
401	Unauthenticated
403	Authenticated but insufficient role
404	Resource doesn’t exist (or you can’t see it)
409	Conflict (duplicate, state mismatch)
422	Validation failure
429	Rate limit exceeded
500	Unhandled exception
503	Dependency unavailable (Postgres down, for instance)

Common error codes

code	status	meaning
invalid_credentials	401	login failed
session_expired	401	cookie expired
insufficient_role	403	missing role for action
not_found	404	resource missing
conflict_duplicate_name	409	unique constraint violated
conflict_state	409	action requires different state (e.g. retry on running task)
validation_failed	422	see errors array
rate_limited	429	see Retry-After header
agent_offline	503	target agent not connected
command_timeout	504	agent didn’t respond in time

Language

Error detail is operator-friendly English. For user-facing UI, switch on code and render your own translated message.

Tracing

Every error response includes X-Request-Id header - pass it when filing a bug.