feat: expose error types as a dimension and in expressions

docs-website/docs.json

@@ -95,7 +95,8 @@
                 "pages": [
                   "router/configuration",
                   "router/configuration/config-design",
-                  "router/configuration/template-expressions"
+                  "router/configuration/template-expressions",
+                  "router/configuration/error-types"
                 ]
               },
               "router/mcp",

docs-website/router/configuration/error-types.mdx

@@ -0,0 +1,30 @@
+---
+title: "Error Types"
+description: "Router error type classifications for metrics and expressions"
+icon: "triangle-exclamation"
+---
+
+When an error occurs during request processing, the router classifies it into one of the following types. This classification is available via:
+- **Expressions**: `request.errorType` and `subgraph.request.errorType` (see [Template Expressions](/router/configuration/template-expressions))
+- **Metrics**: the `wg.error.type` OTEL attribute (or `wg_error_type` in Prometheus)
+
+| Value | Description |
+|---|---|
+| `rate_limit` | The request was rejected because the client exceeded the configured rate limit. |
+| `unauthorized` | The request failed authentication or authorization. |
+| `context_canceled` | The request was canceled, typically because the client disconnected before the response was sent. |
+| `context_timeout` | The request timed out before a response could be produced. |
+| `upgrade_failed` | A WebSocket upgrade request to a subgraph failed. |
+| `edfs` | An error occurred in a Cosmo Streams (EDFS) data source. |
+| `invalid_ws_subprotocol` | The client requested an unsupported WebSocket subprotocol. |
+| `edfs_invalid_message` | A message received from a Cosmo Streams backend could not be parsed as valid JSON. |
+| `merge_result` | The router failed to merge results from multiple subgraph responses. |
+| `streams_handler_error` | An error occurred while handling a Cosmo Streams event. |
+| `operation_blocked` | The operation was rejected by the operation blocker (e.g. blocked operation type or safelist violation). |
+| `persisted_operation_not_found` | A persisted operation was requested but could not be found. |
+| `validation_error` | The GraphQL operation failed parsing or validation against the schema. |
+| `input_error` | The request body was malformed or otherwise invalid (e.g. invalid JSON, missing query). |
+| `subgraph_error` | One or more subgraphs returned an error during execution. |
+| `unknown` | An error occurred that does not match any known category. |
+| `publish_error` | A Cosmo Streams publish operation failed (Kafka, NATS, or Redis). Only appears on stream produce/consume metrics. |
+| `request_error` | A Cosmo Streams NATS request-reply operation failed. Only appears on stream produce/consume metrics. |

docs-website/router/configuration/template-expressions.mdx

@@ -58,6 +58,7 @@ The `request` object is a read-only entity that provides details about the incom
 - `request.url.port`
 - `request.trace.sampled`
 - `request.error`
+- `request.errorType` — The [error type classification](#error-types) as a string. Only set when an error occurred.
 
 ### Operation Object
 
@@ -163,6 +164,7 @@ It contains the following properties:
 #### SubgraphRequest Properties
 
 - `subgraph.request.error` (error): Any error that occurred during the subgraph request
+- `subgraph.request.errorType` (string): The [error type classification](#error-types) for the subgraph request. Only set when an error occurred.
 - `subgraph.request.clientTrace` (ClientTrace): Contains tracing information about the client connection
 
 #### SubgraphResponse Properties
@@ -242,6 +244,22 @@ request.error != nil ? response.body.raw : ''
 You can use expressions to specify the conditions for retries upon subgraph request failures. However, this uses a different expression context, which can be found [here](/router/traffic-shaping/retry#conditional-retry-with-expressions).
 
 
+### Error Types
+
+See the [Error Types](/router/configuration/error-types) reference for the full list of error classifications available via `request.errorType` and `subgraph.request.errorType`.
+
+#### Example expressions
+
+```bash
+# Log the response body only for unauthorized errors
+request.errorType == 'unauthorized' ? response.body.raw : ''
+```
+
+```bash
+# Check if a subgraph had a timeout
+subgraph.request.errorType == 'context_timeout'
+```
+
 ### Additional Notes
 
 - A Request for Comments (RFC) is [open](https://github.com/wundergraph/cosmo/pull/1481) for feedback on the complete API specification. Future implementations will be driven by customer requirements.

docs-website/router/metrics-and-monitoring.mdx

@@ -177,6 +177,8 @@ You can use the `router.http.requests.error` metric to track errors across route
 
 * `http.status_code`: The status code of the response.
 
+* `wg.error.type`: Classifies the error into a specific category. This attribute is attached to both router-level and subgraph-level request metrics when an error occurs. Only set when an error is present. See [Error Types](/router/configuration/error-types) for the full list of possible values.
+
 You have two ways to query for errors. Both metrics can be quite useful depending on the query scenario. In general, we recommend to use the `router.http.requests.error` metric.
 
 #### Subgraph specific
@@ -283,7 +285,7 @@ The name of the destination of the messaging backend (topic, queue, etc)
 The provider id as specified in the router configuration
 
 * `wg.error.type`:
-A generic error type to indicate an error occurred. This is available only for `router.streams.sent.messages` at this moment, as we do not catch message receive errors.
+The error type classification. For Cosmo Streams metrics, this indicates a send error. See [Error Types](/router/configuration/error-types) for the full list of possible values.
 
 
 ### Connection Metrics

docs-website/router/metrics-and-monitoring/prometheus-metric-reference.mdx

@@ -159,7 +159,7 @@ The name of the destination of the messaging backend (topic, queue, etc)
 The provider id as specified in the router configuration
 
 * `wg_error_type`:
-A generic error type to indicate an error occurred. This is available only for `router.streams.sent.messages` at this moment, as we do not catch message receive errors.
+The error type classification. For Cosmo Streams metrics, this indicates a send error. See [Error Types](/router/configuration/error-types) for the full list of possible values.
 
 #### Examples