Tunnel Error Codes
Understand errors returned when a published tunnel cannot route a request.
rstream returns a protocol-aware error when a request reaches an Engine but cannot be routed to a published tunnel. The error code distinguishes a missing live route from a temporary edge failure and remains stable across HTML, JSON, plain-text, and gRPC responses.
| Code | HTTP status | gRPC status | Meaning |
|---|---|---|---|
RSTREAM_TUNNEL_UNAVAILABLE | 404 | 5 NOT_FOUND | No live route is available for the hostname. |
RSTREAM_EDGE_UNAVAILABLE | 503 | 14 UNAVAILABLE | The routing path is temporarily unavailable. |
RSTREAM_TUNNEL_UNAVAILABLE
RSTREAM_TUNNEL_UNAVAILABLE means that the Engine has no live tunnel route for the requested hostname. A stable or custom domain can remain valid while the device is offline, the rstream process is stopped, or its tunnel has not reconnected yet. It can also indicate that the requested hostname is no longer assigned to a tunnel.
The original URL can be retried after the device and tunnel return online. Tunnel owners can confirm runtime state with:
rstream tunnel list -o jsonThe HTTP response uses status 404. Native gRPC over HTTP/2 receives grpc-status: 5 (NOT_FOUND).
RSTREAM_EDGE_UNAVAILABLE
RSTREAM_EDGE_UNAVAILABLE means that the Engine could not complete the routing lookup or reach the edge responsible for the tunnel. The device and tunnel may still be online, so restarting the device is not the first recovery action.
The HTTP response uses status 503 and includes Retry-After: 3. Retrying the same URL is normally sufficient. A persistent error warrants checking tunnel state and Engine observability before restarting the tunnel process. Native gRPC over HTTP/2 receives grpc-status: 14 (UNAVAILABLE).
Response formats
Browser GET and HEAD requests can receive the branded HTML page when the managed Engine feature is enabled for the requested hostname. The page is served directly by the Engine on the original URL; it is not a redirect to the Control plane. Custom domains require explicit offline-page consent and a valid cached certificate.
Clients that request JSON receive an application/problem+json document with code, status, title, and a documentation type. Other HTTP requests receive a compact plain-text response. HTTP upgrade requests never receive HTML. Native gRPC over HTTP/2 receives the corresponding gRPC status without an HTML body.
The branded HTML page is not available in Community Edition because that edition has no associated Control plane UI. Non-HTTP traffic also remains protocol-native and does not receive an HTML page.