Skip to main content

Errors

Similar to the familiar "404 Not Found" and "500 Internal Server Error" status codes you may have seen in HTTP, Connect uses a set of 16 error codes. In the Connect protocol, an error is always represented as JSON, and is easily readable in the developer tools of your browser. For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": "invalid_argument",
  "message": "sentence cannot be empty"
}

With the gRPC-web protocol, errors are usually not human-readable, but Connect provides a common type that represents errors consistently across all supported protocols.

Working with errors​

All errors are represented by ConnectError, a subtype of the built-in Error class. Using a try-catch block, we can catch any error that occurred during a call:

import { ConnectError } from "@connectrpc/connect";

try {
  await client.say({sentence: ""});
} catch (err) {
  // We have to verify err is a ConnectError
  // before using it as one.
  if (err instanceof ConnectError) {
    err.code;    // Code.InvalidArgument
    err.message; // "[invalid_argument] sentence cannot be empty"
  }
  // Alternatively, we can use ConnectError.from()
  // It returns a ConnectError as is, and converts any
  // other error to a ConnectError.
  const connectErr = ConnectError.from(err);
  connectErr.code;    // Code.InvalidArgument
  connectErr.message; // "[invalid_argument] sentence cannot be empty"
}

Error codes​

The code property holds one of Connect's error codes. All error codes are available through the TypeScript enumeration Code. Note that a code is an integer value, but can easily be converted to and from a string value.

import { Code } from "@connectrpc/connect";

let code = Code.InvalidArgument;
code; // 3
let name = Code[code]; // "InvalidArgument"
let val: Code = Code["InvalidArgument"]; // 3

Error messages​

The message property contains a descriptive error message. In most cases, the message is provided by the backend implementing the service. Because message is the only property that shows up in the browser console for uncaught errors, the error message is always prefixed with the error code. In case you do want the original error message without a code prefix, use the property rawMessage.

err.message; // "[invalid_argument] sentence cannot be empty"
if (err.code == Code.InvalidArgument) {
  err.rawMessage; // "sentence cannot be empty"
}

Metadata​

If you catch an error, your program takes an exception from the regular code path, but you might still want to access a header or trailer value. Connect provides a union of header and trailer values in the metadata property as a simple Headers object:

err.metadata.get("Custom-Header-Value");
err.metadata.get("Custom-Trailer-Value");

Error details​

On the wire, error details are wrapped with google.protobuf.Any, so that a server or middleware can attach arbitrary data to an error. Using the method findDetails(), you can decode the details from an error.

The method takes a protobuf message type as an argument, and returns an array of decoded messages of this type.

This example looks up a localized error message in the users preferred language:

import { ConnectError } from "@connectrpc/connect";
import { LocalizedMessage } from "./error_details_pb.js";

function handle(err: ConnectError) {
  const localized = err.findDetails(LocalizedMessage)
    .find(i => i.locale === navigator.language);
  console.log(localized?.message);
}

We are using the protobuf message google.rpc.LocalizedMessage in this example, but any protobuf message can be transmitted as error details.

Alternatively, findDetails() takes a registry as an argument. See the protobuf-es documentation for details.

For some practical examples of handling specific errors, check out the Cancellation & Timeouts docs.