Registration Returns 500, but the Account Was Created

Decision: the response follows the durable account state

Account commit

Absent, committed, or unknown after a timeout. This decides whether registration itself failed.

Verification artifact

Not attempted, store failed, stored, or handed to a sender. This decides whether verification can proceed.

Email outcome

Sender acceptance, provider events, receiver acceptance, and inbox visibility remain later evidence.

Three policies need three different invariants

1. Required. Keep the usable account behind confirmation. A durable pending registration may return 202, but no password session or active account exists until verification succeeds.
2. Optional. Commit the account as the primary result. Verification can be pending, retry-scheduled, temporarily unavailable, or complete without changing registration success.
3. None. Do not let token storage or mail delivery participate in registration success at all.

A truthful operation contract

POST /registrations  Idempotency-Key: random-client-operation-id

account commit rolled back:
  503 { registration: "not_created", retry: "same_key" }

account commit outcome unknown:
  202 { registration: "reconciling", operationRef }

optional account committed; token store or sender failed:
  202 { registration: "created",
        verification: "retry_scheduled" | "unavailable",
        operationRef }

required pending registration stored:
  202 { registration: "pending_verification", operationRef }

Invariant: a retry with the same key returns or resumes
           the same logical registration.

Use bounded states and opaque operation references. Do not return a provider error, raw token, recipient address, password hash, Redis key, or internal account identifier to the client.

Implementation order

1. Give each logical registration an idempotency key and persist its operation state.
2. For optional verification, commit the account and a durable verification job in the same primary transaction when possible.
3. Let a worker create or rotate the single-use verification artifact, call the sender, and record bounded attempt state. Every retry targets the same account and logical verification job.
4. Return account creation independently from verification delivery. Emit metrics and logs for token-store and sender failures instead of swallowing them.
5. Provide a rate-limited resend or resume path that operates on the existing unverified account.
6. Track a provider message ID and later delayed, bounced, rejected, complained, or receiver-accepted events without rewriting account state.

What the current AuthKit source proves

open-rails/authkit issue 56 reports a live Optional-policy failure where Redis rejected the verification-token write after the account had already been created. In reviewed master revision dbd0071021d23ef1412c3878fdffc31ba002cfdb, the Optional email branch calls createEmailRegistrationUser(), which commits its PostgreSQL transaction, before storeEmailVerificationTokens() and SendVerification().

Both later operations return errors to the HTTP handler. That handler maps an unclassified error to registration_failed; however, a successful Optional path immediately reads the committed account and issues its registration tokens because only the Required policy sets requiresVerification. The failure response therefore contradicts the same branch's account-availability contract.

The smallest behavioral correction is to treat token-store and sender failures after the Optional account commit as verification outcomes, preserve telemetry, and let the handler complete registration. The stronger design commits an idempotent verification job with the account and gives retries a stable operation identity.

Failure tests before release

1. Force the verification store to fail after the Optional account commit. Prove the response says created, one account exists, authentication follows Optional policy, and one recovery job is recorded.
2. Force the sender to fail after token storage. Prove registration remains created, the token is not exposed, and resend resumes the same account.
3. Drop the HTTP response after commit, then replay the same idempotency key. Prove the original result returns and no duplicate account or message is created.
4. Run two concurrent retries. Prove one logical registration and one active verification artifact.
5. Under Required policy, fail the pending-state write. Prove no usable account or password session exists.
6. Return sender success and then ingest a bounce. Prove verification delivery changes while registration state does not.