Skip to content

Errors

SeekAuth answers errors in one of two shapes. The management API and the account API use { "code", "message" }. The protocol endpoints (/authorize, /token, /userinfo, /revoke, /introspect, /session-ticket and the embedded login) use the OAuth shape, { "error", "error_description" }. The SDKs read both: see auth-js errors.

{ "code": "plan_limit", "message": "The Free plan includes 1 app with accounts of its own. The Pro plan includes more." }

message is written for a person and may change; branch on code and the status.

code Status Default message
bad_request 400 Says what is wrong with the request.
name_not_allowed 400 A name (an app’s, a group’s, a workspace’s, a client’s, an API key’s), a login page’s heading or line, or a custom provider’s label or id cannot be used: it passes for one of SeekAuth’s own products, holds control or invisible characters, or (a name of an app, a group or a workspace) is made only of words such as support, login or admin. About those words alone; another slug will not help.
invalid_entity 422 “Validation error in request body, …”, with an errors member naming the fields.
no_token 401 “No token, authorization denied”. WWW-Authenticate: Bearer.
token_invalid 401 “Token is not valid, authorization denied”. WWW-Authenticate: Bearer error="invalid_token".
step_up_required 401 “A more recent or stronger login is required”. See below.
plan_limit 402 Says what the plan includes and which plan includes more.
forbidden 403 “Forbidden”: the caller’s role is too weak, or the caller is not a person where one is needed.
origin_not_allowed 403 “This origin is not allowed for the client”.
not_found 404 “Not found”. Also every unknown path, and anything in a workspace the caller has no role in.
unknown_host 404 “No environment is served on this host”.
conflict 409 Says what conflicts: a taken slug or id, the last owner, a reserved name, a limit with no larger plan.
address_unconfirmed 409 Provisioning from Seek: a developer account already has the person’s email address and has never confirmed it. They sign in to the dashboard with a code sent to that address, then try again.
sole_owner 409 A developer account cannot be deleted while it is the only owner of a workspace; names them, with a workspaces member.
rate_limited 429 “Too many attempts, try again later”. Retry-After says how many seconds to wait.
internal_error 500 “An internal server error occurred”. Nothing more is said.
upstream_error 502 A service SeekAuth relies on did not answer, such as the DNS resolver or the payment provider.
Member With Meaning
errors invalid_entity The fields that failed validation.
acr_values step_up_required "aal2" when a second factor is needed, else null.
max_age step_up_required Seconds: how recent the login must be.
workspaces sole_owner [{ id, name }]: the workspaces to give another owner, or delete, first.

step_up_required also carries the same in its header, for clients that read only that:

WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="aal2", max_age="600"

A body that is not valid JSON, a missing JSON content type, a missing or mistyped field, or a path segment that is not a UUID where one is expected, is refused before the request reaches SeekAuth’s own checks. Those answers are plain text, not the shape above: 400 for invalid JSON, 415 for a missing Content-Type: application/json, 422 for a missing or mistyped field, 400 for a bad path. Fields SeekAuth does not know are ignored, not refused.

{ "error": "invalid_grant", "error_description": "the code is invalid or expired" }

The RFC 6749 shape, with Cache-Control: no-store and Pragma: no-cache. On /authorize, after the client and redirect URI are verified, the same two values travel as query parameters of the redirect, with state and iss; see /authorize errors.

error Status Where
invalid_request 400 Everywhere: a missing or malformed parameter.
invalid_client 401 /token, /revoke, /introspect: client authentication failed. WWW-Authenticate: Basic.
invalid_grant 400 /token: the code or refresh token is not good, was reused, or its session or user ended.
unauthorized_client 400 /authorize, /token: this kind of client may not do this. Also an origin the client does not allow.
unsupported_grant_type 400 /token
unsupported_response_type 400 /authorize
invalid_scope 400 /token: a refresh asked for more than was granted.
invalid_target 400 /authorize, /token: resource names an API the client may not ask for.
invalid_dpop_proof 400 /token, /userinfo, /session-ticket: a missing, invalid, replayed or mismatched proof. WWW-Authenticate: DPoP error="invalid_dpop_proof", algs="ES256".
invalid_token 401 /userinfo, /session-ticket, the embedded login’s step-up: the access token is not good. WWW-Authenticate: Bearer error="invalid_token".
insufficient_scope 403 /userinfo: the token has no openid scope.
access_denied 403 /authorize, /token: the app does not let this user in.
login_required 400 /authorize with prompt=none and nobody signed in.
interaction_required 400 /authorize with prompt=none when the request needs the user.
request_not_supported 400 /authorize with request or request_uri.
invalid_session 400 The embedded login: the login attempt is unknown or has ended. Start again.
insufficient_authorization 403 The embedded login: not an error to show, but the next challenge. See /authorize-challenge.
temporarily_unavailable 429 Too many attempts. Retry-After says how many seconds to wait.
temporarily_unavailable 503 /token, a refresh the service came to too late or could not finish in time. Nothing was used up; see a refresh that gets no answer.
server_error 500 Something failed on the server.

Extra members can come with an error, such as the embedded login’s auth_session and challenge. Retry-After is exposed to browsers by CORS, as is WWW-Authenticate.