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.
API errors
Section titled “API 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. |
Extra members
Section titled “Extra members”| 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"Malformed requests
Section titled “Malformed requests”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.
OAuth errors
Section titled “OAuth errors”{ "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.