Exceptions¶

Social Auth exposes structured exceptions so applications can choose recovery without matching provider descriptions or exception messages.

Catch SocialAuthBaseException for all Social Auth failures, including configuration errors. Catch AuthException for authentication-flow failures. Both retain their existing inheritance, including ValueError. Configuration errors inherit directly from SocialAuthBaseException.

Exception families¶

AuthConfigurationError: Missing or invalid settings, unavailable backends, or unsupported features.
AuthInputError: Missing or invalid request or application input.
AuthSessionError: Missing authentication context, state mismatch, or a different initiating user.
AuthResponseError: Malformed provider responses or failed signature, claim, nonce, or expiry validation.
AuthCredentialError: Rejected credentials, rejected authorization codes, revoked tokens, or required reauthentication.
AuthPolicyError: Application authentication, membership, or disconnect policy rejection.
AuthAssociationError: Local account conflicts or unsafe identifier migration.
AuthProviderError: Connection, timeout, TLS, rate-limit, availability, or HTTP failures.
AuthCanceled: Explicit authorization cancellation or refusal.
AuthUnknownError: Authentication failures without a known classification.

Structured attributes¶

Each exception exposes code, source, stage, and recovery. Codes are stable machine-readable strings; messages and diagnostic descriptions are not part of the classification contract.

source identifies the failing boundary, not who is responsible: configuration, request, session, provider_response, local_policy, storage, or unknown.

stage identifies the operation: begin, callback, token_exchange, token_validation, user_info, pipeline, refresh, disconnect, or unknown. Custom integrations should supply the stage at the raise site.

recovery suggests an action: none, correct_input, restart_login, reauthenticate, retry_later, check_provider_profile, use_existing_account, or contact_administrator. These hints do not perform retries or redirects and do not determine whether to report a failure.

Optional attributes are backend, parameter, claim, provider_code, status_code, and retry_after. retry_after preserves the provider’s HTTP header; applications must interpret it before using it.

str(exception) and exception.args contain a safe default message. Provider descriptions are available separately in detail. context is an explicitly supplied mapping for diagnostic identifiers, such as user ID and provider UID. Original exceptions remain available through exception chaining. Do not send diagnostics, raw responses, or identifying context to client URLs or flash messages. Do not log tokens, cookies, or full authentication assertions.

public_metadata() returns only error_code, error_source, error_stage, and error_recovery.

from social_core.exceptions import AuthResponseError, AuthException

if "sub" not in claims:
    raise AuthResponseError(
        backend, code="missing_claim", claim="sub", stage="token_validation"
    )

try:
    authenticate()
except AuthException as error:
    if error.code == "response_expired":
        show_restart_login_message()
    else:
        show_generic_authentication_message()

Application-specific codes should have a namespace, for example myapp.registration_disabled. Explicitly set their source and recovery. Unknown codes use the family’s safe default message and metadata. Never derive a code from a free-form message.

Reason codes¶

Defaults are listed below. A raise site can override source or recovery when its operation supplies more precise information.

Code	Source	Suggested recovery
`missing_setting`	`configuration`	`contact_administrator`
`invalid_setting`	`configuration`	`contact_administrator`
`unsupported_feature`	`configuration`	`contact_administrator`
`backend_missing`	`configuration`	`contact_administrator`
`missing_parameter`	`request`	`correct_input`
`invalid_parameter`	`request`	`correct_input`
`session_context_missing`	`session`	`restart_login`
`state_mismatch`	`session`	`restart_login`
`user_mismatch`	`session`	`restart_login`
`malformed_response`	`provider_response`	`contact_administrator`
`missing_claim`	`provider_response`	`contact_administrator`
`invalid_claim`	`provider_response`	`contact_administrator`
`invalid_signature`	`provider_response`	`contact_administrator`
`nonce_mismatch`	`provider_response`	`restart_login`
`response_expired`	`provider_response`	`restart_login`
`response_not_yet_valid`	`provider_response`	`contact_administrator`
`invalid_expiry`	`storage`	`contact_administrator`
`profile_email_missing`	`provider_response`	`check_provider_profile`
`authorization_code_rejected`	`provider_response`	`restart_login`
`credential_rejected`	`provider_response`	`reauthenticate`
`token_revoked`	`provider_response`	`reauthenticate`
`reauthentication_required`	`storage`	`reauthenticate`
`email_verification_rejected`	`request`	`restart_login`
`authentication_disallowed`	`local_policy`	`contact_administrator`
`membership_required`	`local_policy`	`contact_administrator`
`disconnect_disallowed`	`local_policy`	`none`
`identity_in_use`	`storage`	`use_existing_account`
`email_in_use`	`storage`	`use_existing_account`
`username_in_use`	`storage`	`use_existing_account`
`identifier_migration_conflict`	`storage`	`contact_administrator`
`connection_failed`	`provider_response`	`retry_later`
`timeout`	`provider_response`	`retry_later`
`tls_error`	`provider_response`	`contact_administrator`
`rate_limited`	`provider_response`	`retry_later`
`unavailable`	`provider_response`	`retry_later`
`http_error`	`provider_response`	`contact_administrator`
`authorization_declined`	`provider_response`	`none`
`unknown_error`	`unknown`	`contact_administrator`

Provider failures¶

HTTP status alone does not establish cancellation, expired credentials, or a local policy rejection. Shared HTTP handling retains status and structured provider codes. Unknown provider codes remain provider errors.

For OAuth, invalid_client is a configuration failure and invalid_grant is credential rejection. The latter does not establish expiry. Explicit access_denied indicates authorization refusal. HTTP 429 and server errors receive retry-later guidance; TLS verification failures require administrator attention without suggesting that verification be disabled.

Migration from legacy exceptions¶

This is a breaking change. SocialAuthBaseException and AuthException remain available for broad catches. AuthCanceled and AuthUnknownError also remain available, so catches of these types can be retained. Removed names have no aliases or wrappers. Update custom backends, pipelines, and catches of removed types together with the library upgrade.

Previous exception	Replacement
`AuthFailed` / `AuthTokenError`	Choose response, credential, session, policy, or provider failure from the actual cause.
`AuthMissingParameter` / `AuthInvalidParameter`	Input errors for request data; configuration errors for settings; response errors for provider fields.
`AuthStateMissing` / `AuthStateForbidden`	Session errors with `session_context_missing` / `state_mismatch`.
`AuthUserMismatch`	`AuthSessionError` with `user_mismatch`.
`AuthTooManyRequests`	`AuthProviderError` with `rate_limited`.
`AuthForbidden`	Local policy errors; session errors for user mismatch; provider errors for HTTP rejection.
`AuthAlreadyAssociated`	Association errors with an explicit identity, username, email, or migration-conflict code.
`AuthTokenRevoked` / `AuthReauthenticationRequired`	Credential errors with `token_revoked` / `reauthentication_required`.
`AuthConnectionError` / `AuthUnreachableProvider`	Provider errors distinguishing connection, timeout, TLS, rate limit, and availability.
`InvalidEmail`	Credential error with `email_verification_rejected`.
`NotAllowedToDisconnect`	Policy error with `disconnect_disallowed`.
`InvalidExpiryValue`	Response error with `invalid_expiry`, source `storage`, and `parameter` identifying the field.
`WrongBackend` / `MissingBackend`	Configuration error with `backend_missing`.
Strategy/configuration errors / `AuthNotImplementedParameter`	Configuration errors with missing/invalid settings or `unsupported_feature`.

Previously, AuthStateMissing meant missing session state, while missing callback state raised AuthMissingParameter. Preserve that distinction when migrating: use a session error for missing saved state and an input error for a missing callback parameter.

Construct failures with a backend (or None where unavailable) and keyword metadata. Keep provider descriptions in diagnostic positional arguments. For example, replace AuthTokenError(backend, "Signature has expired") at a confirmed expiry boundary with:

AuthResponseError(
    backend,
    "Signature has expired",
    code="response_expired",
    stage="token_validation",
)

Do not translate that text into a code elsewhere in the application.