Handle Errors with Lambda Connectors

Introduction

By default, lambda connectors return a generic internal error message whenever an exception is encountered in your custom business logic and log the details of the error in the OpenTelemetry trace associated with the request.

The Native Data Connector specification identifies a valid set of status codes which a connector can return to your API consumers.

How detailed should error messages be?

Exposing stack traces to end users is generally discouraged. Instead, API administrators can review traces logged in the OpenTelemetry traces to access detailed stack trace information.

Return custom error messages

Lambda connectors allow you to throw classes of errors with your own custom message and metadata to indicate specific error conditions. These classes are designed to provide clarity in error handling when interacting with your data sources. To explore the available error classes, use your editor's autocomplete or documentation features to view all supported classes and their usage details.

TypeScript

TypeScript examples:

import * as sdk from "@hasura/ndc-lambda-sdk";

/** @readonly */
export function updateResource(userRole: string): void {
  if (userRole !== "admin") {
    throw new sdk.Forbidden("User does not have permission to update this resource", { role: userRole });
  }
  console.log("Resource updated successfully.");
}

/** @readonly */
export function createResource(id: string, existingIds: string[]): void {
  if (existingIds.includes(id)) {
    throw new sdk.Conflict("Resource with this ID already exists", { existingId: id });
  }
  console.log("Resource created successfully.");
}

/** @readonly */
export function divide(x: number, y: number): number {
  if (y === 0) {
    throw new sdk.UnprocessableContent("Cannot divide by zero", { myErrorMetadata: "stuff", x, y });
  }
  return x / y;
}

Python

Python examples:

# There are different error types including: BadRequest, Forbidden, Conflict, UnprocessableContent, InternalServerError, NotSupported, and BadGateway
@connector.register_query
def error():
    raise UnprocessableContent(message="This is an error", details={"Error": "This is an error!"})

Go

Go examples:

package functions

import (
	"context"
	"fmt"

	"github.com/hasura/ndc-sdk-go/schema"
	"hasura-ndc.dev/ndc-go/types"
)

// A hello argument
type HelloArguments struct {
	Greeting string `json:"greeting"`
	Count    *int   `json:"count"`
}

// A hello result
type HelloResult struct {
	Reply string `json:"reply"`
	Count int    `json:"count"`
}


func FunctionHello(ctx context.Context, state *types.State, arguments *HelloArguments) (*HelloResult, error) {
	count := 1
	authorized := false // This is just an example

	if !authorized {
		return nil, schema.UnauthorizeError("User is not authorized to perform this operation", map[string]any{
			"function": "hello",
		})
	}

	if arguments.Count != nil {
		count = *arguments.Count + 1
	}
	return &HelloResult{
		Reply: fmt.Sprintf("Hi! %s", arguments.Greeting),
		Count: count,
	}, nil
}

Access OpenTelemetry traces

Traces — complete with your custom error messages — are available for each request. You can access these by clicking on View Trace in the bottom-right corner of the GraphiQL explorer in the console after running a request.

Additionally, you can access the traces list under the Insights tab.