Errors¶

Every failed message is answered with an error envelope:

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "version": "1.0",
  "source": "dichit-backend",
  "timestamp": "2026-08-05T10:00:00.000Z",
  "sequence": 45219,
  "data": {
    "code": "FORBIDDEN",
    "message": "You are not authorized to perform this WebSocket action."
  },
  "meta": {
    "traceId": "trc_01HQ5BXWYP1Y5RX0W5X0W5X0W5X"
  }
}

• id echoes the failing request's id when the envelope could be parsed; a server-generated id is used otherwise.
• data.message is a safe, client-facing description — never a stack trace or an internal identifier.
• data.code is the stable machine-readable error code.
• sequence is the server-assigned per-connection sequence (see protocol.md).
• Error responses are always delivered on the same connection; an error never terminates the connection (connection-level failures use close codes instead, see connection.md).

Reference: protocol.md · connection.md · authentication.md

Error codes¶

The canonical error codes are produced by the platform's central WebSocket error mapper.

Retryability¶

• RATE_LIMITED and INTERNAL may be retried after backoff.
• BAD_REQUEST, FORBIDDEN, NOT_FOUND, CONFLICT should not be retried as-is; fix the request first.
• UNAUTHORIZED requires a fresh token + reconnection, not a naive retry.

Requested/aliased error codes¶

Some integrations and earlier drafts referenced the following names. They are not emitted by the current server but are part of the historical contract. Map them as follows:

Error examples¶

The examples below omit the envelope boilerplate (version, source, timestamp, sequence, meta) for brevity; those fields are always present on the wire.

BAD_REQUEST — invalid payload¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "BAD_REQUEST",
    "message": "Invalid WebSocket message."
  }
}

An unknown event type also returns BAD_REQUEST:

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "BAD_REQUEST",
    "message": "Unsupported WebSocket event type: auction.dance"
  }
}

UNAUTHORIZED¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required."
  }
}

FORBIDDEN — permission denied¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "FORBIDDEN",
    "message": "You are not authorized to perform this WebSocket action."
  }
}

Room denial:

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "FORBIDDEN",
    "message": "Only admins can join the admins room."
  }
}

NOT_FOUND¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "NOT_FOUND",
    "message": "Auction not found."
  }
}

CONFLICT — state conflict¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "CONFLICT",
    "message": "State conflict."
  }
}

RATE_LIMITED¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "RATE_LIMITED",
    "message": "Too many WebSocket messages."
  }
}

INTERNAL¶

{
  "id": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "type": "error",
  "data": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred."
  }
}

Connection-level failures¶

Failures during the handshake never produce an error envelope; they close the connection with a WebSocket close code:

Where errors are raised¶

See the routing pipeline in protocol.md and the authorization diagram in diagrams.md.

Related documents¶

• protocol.md — the error envelope.
• authentication.md — UNAUTHORIZED vs FORBIDDEN.
• rate-limits.md — RATE_LIMITED behaviour.
• connection.md — close codes.