Error Codes

All INK endpoints MUST return structured error responses:

{
  "protocol": "ink/0.1",
  "error": true,
  "code": "invalid_signature",
  "message": "Ed25519 signature verification failed"
}

Error Codes

Code	HTTP Status	Description
invalid_signature	401	Signature verification failed
invalid_delegation	401	agentLink repo commit signature verification failed
expired_message	400	Timestamp outside acceptable window
duplicate_nonce	400	Nonce already seen
unknown_did	404	Could not resolve sender DID
no_agent_link	404	No agentLink record found for sender
encryption_required	400	Intent type requires encrypted payload
decryption_failed	400	Could not decrypt payload
unsupported_version	400	Protocol version not supported
rate_limited	429	Too many requests
handshake_budget_exhausted	429	Per-correlation handshake budget exceeded
sender_rate_limited	429	Per-sender sliding window rate limit exceeded
transport_scope_violation	403	Invocation transport not permitted by delegation token
sender_mismatch	403	Message from field does not match authenticated sender identity
access_denied	403	Requester is not a party to the referenced message
internal_error	500	Agent internal error

Witness Service Error Codes

The witness service returns these additional error codes on its authenticated endpoints.

Code	HTTP Status	Description
missing_authorization	401	No Authorization header present
invalid_auth_scheme	401	Authorization header is not INK-Ed25519 scheme
nonce_replay	401	Nonce has already been used (10-minute window)
duplicate_event_id	409	An event with this ID has already been recorded
invalid_agent_signature	400	Event agentSignature does not verify against the agent’s public key
invalid_agent_id_format	400	Cannot extract a public key from the agentId field
sender_mismatch	401	Transport auth sender does not match body.from
event_agent_mismatch	400	event.agentId does not match submission sender
rate_limit_exceeded	429	Agent has exceeded 30 submissions per minute
forbidden	403	Requester is not a party to the queried message