API Error Reference

OAuth Errors

Authorization and token endpoints use standard OAuth-style error responses.

invalid_request

Missing required parameters or malformed input.

invalid_client

Unknown client, suspended client, or invalid client authentication.

invalid_scope

Requested scope is not allowed for the client.

invalid_grant

Expired, reused, or invalid authorization code or refresh token.

access_denied

User denied the flow or the authorization request could not proceed.

Public Authentication Errors

401 Invalid email or password

Standard password-login failure.

401 Password not set

The account exists but only has social login methods linked.

403 Please verify your email address before logging in

The public user exists but email verification is not complete.

401 No active session found

Returned by GET /api/public/session when the cookie is missing or invalid.

Permission and Access Errors

403 Forbidden

Returned when the bearer token is valid but is not authorized for the requested user/client combination.

404 No permission record found

Returned by permission reads when no record exists for the specified user/client pair.

404 Client not found

Returned when the target OAuth client does not exist.

400 Invalid role

Role must be one of none, user, admin.

400 Invalid status

Status must be one of pending, approved, revoked.

Social Login Errors

google_invalid_state / facebook_invalid_state

Callback state is missing, malformed, expired, or no longer matches the CSRF cookie.

google_callback_failed / facebook_callback_failed

Provider callback failed after redirect.

google_no_email / facebook_no_email

The provider account did not supply a usable email claim for account linking.

Rate Limits and Retry Behavior

Some endpoints return HTTP 429 with retry guidance. Authentication clients should treat 429 responses as transient and retry later.