Error codes

This page lists typical errors and how to interpret them.

The exact format depends on your deployment (some deployments return structured JSON errors; others close a stream/connection).

Authentication and authorization

• UNAUTHENTICATED / 401 / WS close on handshake
  Missing token, invalid token, expired token, or token restricted by IP/region/origin.

• PERMISSION_DENIED / 403
  Token is valid, but the requested tenant/channel is not allowed for publish/subscribe.

Subscription / delivery behavior

• No messages after subscribe
  Often not an error code. Common causes:
  • join window (propagation delay) after subscribe
  • mismatch in tenant/channel spelling
  • token does not allow the subscription rule

See Delivery semantics and Troubleshooting.

WebSocket-specific

WebSocket errors may appear as HTTP status codes during handshake or as close frames.

• 1008 (Policy Violation)
  Often used for forbidden actions or invalid messages (deployment-specific).

• 1009 (Message Too Big)
  Payload/frame exceeds allowed size.

• 1011 (Internal Error)
  Server-side error; retry with backoff.

If your deployment returns a JSON error frame, include at least:

• a stable code string
• a human-readable message
• optional details with tenant/channel and a trace id

gRPC-specific

The gRPC API uses standard status codes:

• UNAUTHENTICATED (16) — missing/invalid token
• PERMISSION_DENIED (7) — forbidden tenant/channel
• INVALID_ARGUMENT (3) — invalid request shape or invalid pattern
• RESOURCE_EXHAUSTED (8) — limits exceeded (payload too large, too many subscriptions, etc.)
• UNAVAILABLE (14) — service unreachable or overloaded; retry with backoff

REST API (token management)

Typical HTTP statuses:

• 400 Bad Request — invalid JSON, invalid expires_at format, invalid channel rule
• 401 Unauthorized — missing/invalid master token
• 404 Not Found — token id not found (for revoke/refresh/list operations, depending on endpoint)
• 200 OK — token operation succeeded

Recommended error list for a “mature product” feel

If you want consistent cross-protocol errors, a small stable set is usually enough:

• INVALID_TOKEN_FORMAT
• TOKEN_EXPIRED
• TOKEN_REVOKED
• ORIGIN_NOT_ALLOWED
• IP_NOT_ALLOWED
• REGION_NOT_ALLOWED
• TENANT_NOT_ALLOWED
• CHANNEL_NOT_ALLOWED_PUB
• CHANNEL_NOT_ALLOWED_SUB
• INVALID_TENANT
• INVALID_CHANNEL
• INVALID_PATTERN
• PAYLOAD_TOO_LARGE
• SLOW_CONSUMER
• INTERNAL_ERROR

Where to surface them:

• WebSocket: JSON error frames + close code when needed
• gRPC: status code + details (grpc-status-details-bin) if you use it
• REST: JSON body with {code, message, details}

Error codes