Error Messages

~9 min · protocol, errors

Level 0Poller

0 XP0/60 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Errors as data, not exceptions

An error message in your protocol is just another message: typed envelope, machine-readable code, human-readable text. The client UI maps codes to behaviors (toast, modal, redirect). Your error format is part of your public API — pick it once and stick to it.

Six standard codes

Cover these six and you have most of REST's error vocabulary translated to WebSocket: invalid_message, unauthorized, forbidden, not_found, rate_limited, internal_error. Add app-specific codes as needed (room_full, session_expired, etc.) but keep them stable across releases.

Code

Error envelope·json

{
  "type":    "error",
  "code":    "rate_limited",
  "message": "you're sending too fast, slow down",
  "details": {
    "retry_after": 5,
    "limit":       "20 messages/second"
  },
  "ref_id":  "abc-123"
}

Standard codes·text

invalid_message   - message did not match envelope or schema
unauthorized      - missing or invalid auth
forbidden         - authenticated but not permitted
not_found         - referenced room/user/resource does not exist
rate_limited      - too many messages too fast
internal_error    - server-side bug or unexpected failure

External links

RFC 7807: Problem Details for HTTP APIs (translatable)

Exercise

Define a six-row error code table for your chat app. For each code, write the trigger condition (server side), the user-facing message (in your UI), and the client-side behavior (toast / modal / redirect / silently retry). Document this as a table in your protocol spec.