Auth
No valid credentials: nobody signed in, an expired session, a bad token or secret. 401.
Intents
Raising one
Name what went wrong. The intent sets the status, the message the caller sees, and any log it writes.
// Nobody is signed in, and this needs a signed-in user
return fail('auth.required');
// The caller was signed in, but the session or link has expired
return fail('auth.expired');
// A sign-in with the wrong email or password
return fail('auth.signin');
// A wrong credential: a bad API token, webhook signature or preview secret
return fail('auth.invalid', 'Preview secret did not match.');HTTP 401
{
"ok": false,
"error": "Sign in required.",
"code": "auth.required"
}Is it an auth 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.*this pageValid 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.*