Errors

Both relays share consistent HTTP error semantics. This page lists the cross-cutting cases; the product pages detail endpoint-specific errors.

Status codes

Status	Meaning	What to do
400	Malformed request.	Fix the payload.
401	Invalid authentication (signature, token, timestamp).	See Authentication (HMAC).
403	Forbidden (tenant suspended, insufficient scope).	Check the tenant status and your privileges.
404	Not found — or scope-masked (system console).	Check the id and your privileges.
409	Conflict (incompatible state, duplicate).	Re-read current state before retrying.
422	Validation failed.	Fix the flagged fields.
429	Rate limit reached.	Slow down; respect the limit headers.
500	Internal error.	Retry with backoff; contact support if persistent.

404 instead of 403 on the system console

The Chat Relay deliberately returns 404 (not 403) on the system console to non-privileged accounts, so as not to reveal the routes’ existence. See Console & system console.

Special case: sudo step-up

The Auth Relay uses a two-call protocol for sensitive actions. The first call returns a 403 with the code SUDO_INSTRUCTION_KEY_REQUIRED and an instruction_id: this is not a terminal error, but an approval request. Re-issue the call after approval with the X-Sudo-Instruction-Key header. See Sudo (step-up).

Common authentication errors

The most frequent 401s come from the signature: signed body differs from the sent body, wrong tenant_secret, or clock skew. The full diagnostic table is on Authentication (HMAC).