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 can be used to improve PromptQL's understanding of errors when they occur.

How detailed should error messages be?

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

That said, the more clarity provided in an error message, the better PromptQL can self-correct and improve its understanding of the function. Clear, descriptive error messages allow PromptQL to learn from errors and provide more accurate interactions with your data over time.

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 PromptQL interacts 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 find these in the Insights tab of your project's console. These traces help you understand how PromptQL is interacting with your data and where improvements can be made to enhance accuracy.