API Errors

Encore provides a standardized format of returning errors from API endpoints.

It looks like this:

// HTTP 404 Not Found
{
    "code": "not_found",
    "message": "sprocket not found",
    "details": null
}

To return this, throw the APIError exception that Encore provides in the encore.dev/api module, with the appropriate error code:

import { APIError, ErrCode } from "encore.dev/api";

throw new APIError(ErrCode.NotFound, "sprocket not found");

// or as a shorthand you can also write:
throw APIError.notFound("sprocket not found");

Error Codes

The ErrCode type in the encore.dev/api module defines error codes for common error scenarios. They are identical to the codes defined by gRPC for interoperability.

The table below summarizes the error codes.

Additional details

To attach additional structured details to errors, use the withDetails method on an APIError. The details will be returned with the error to external clients.