API Errors

Returning structured error information from your APIs

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", }

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.

CodeStringHTTP Status
OK"ok"200 OK
Canceled"canceled"499 Client Closed Request
Unknown"unknown"500 Internal Server Error
InvalidArgument"invalid_argument"400 Bad Request
DeadlineExceeded"deadline_exceeded"504 Gateway Timeout
NotFound"not_found"404 Not Found
AlreadyExists"already_exists"409 Conflict
PermissionDenied"permission_denied"403 Forbidden
ResourceExhausted"resource_exhausted"429 Too Many Requests
FailedPrecondition"failed_precondition"400 Bad Request
Aborted"aborted"409 Conflict
OutOfRange"out_of_range"400 Bad Request
Unimplemented"unimplemented"501 Not Implemented
Internal"internal"500 Internal Server Error
Unavailable"unavailable"503 Unavailable
DataLoss"data_loss"500 Internal Server Error
Unauthenticated"unauthenticated"401 Unauthorized