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.
Code | String | HTTP 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 |