Failure
Our fault or a dependency’s. The caller sees a generic message; the details are logged. 5xx.
Intents
Raising one
Name what went wrong. The intent sets the status, the message the caller sees, and any log it writes.
// Our fault: a bug, a failed database call. The caller gets a generic message; the details go to the log
return fail('failure.internal', undefined, { cause: error });
// A service we depend on failed or timed out: a feed, an email provider, an API
return fail('failure.upstream', 'Feed host timed out.', { cause: error });
// Temporarily unavailable: maintenance, missing configuration, overload
return fail('failure.unavailable', 'SUPABASE_SERVICE_ROLE_KEY is not set.');HTTP 500
{
"ok": false,
"error": "Something went wrong. Try again.",
"code": "failure.internal"
}{
"intent": "incident.failed",
"level": "error",
"alert": true,
"message": "Something went wrong. Try again.",
"data": {
"intent": "failure.internal",
"cause": {
"name": "PostgresError",
"message": "connection terminated unexpectedly",
"stack": "PostgresError: connection terminated…"
}
},
"time": "2026-10-09T12:00:00.000Z"
}Is it a failure error?
Find the row that describes your case, and use the domain on the right.
If the problem is
Use
The caller’s request was wrong: unreadable, incomplete, or a value that breaks a rule. 400 or 422.
request.*No valid credentials: nobody signed in, an expired session, a bad token or secret. 401.
auth.*Valid credentials, but not allowed to do this. 403.
permission.*The thing asked for is not there, as far as the caller may know. 404.
record.*The request clashes with the current state: it already exists, or it is not possible yet. 409.
conflict.*Too many requests, or an allowance used up. 429.
limit.*Our fault or a dependency’s. The caller sees a generic message; the details are logged. 5xx.
failure.*this page