Skip to content

fix(api): Answer duplicate contacts with 409 instead of an empty 500 - #11

Merged
sagnik11 merged 1 commit into
mainfrom
autter/contacts-duplicate-409
Nov 14, 2026
Merged

sagnik11 merged 1 commit into
mainfrom
autter/contacts-duplicate-409

Conversation

@sagnik11

Copy link
Copy Markdown
Member

Why

Our backend sends each new signup to Harbour with POST /api/v1/lists/{listId}/contacts. Three contacts have been getting HTTP 500 with an empty body on every hourly retry since 17 Oct, 20 Oct and 5 Nov. The backend logs status: 500, body: "" from harbour.autter-logs.com (attempt 960 and counting).

The route did a plain insert(contacts). When the contact was already in the list, the (list_id, email) unique constraint threw, nothing caught it (the route and withApiAuth both let it through), and Next.js sent its empty 500. The client counts 2xx and 409 as success and retries anything else, so a duplicate is retried forever.

What

  • Create contact (v1): insert with onConflictDoNothing on (list_id, email). On a conflict, answer 409 in the usual envelope:
    { "data": { "id", "email", "status" }, "meta": {}, "error": "A contact with this email already exists in this list" }.
    No confirmation or verification job is queued for the existing contact, and no audit entry is written.
  • Side effects after the insert (confirmation job, verification job, audit log) are each wrapped and logged, so they cannot fail a request whose contact was already created. logAudit and enqueueContactEmailVerification already swallow their own errors today, so this is defensive rather than a live bug.
  • Catch-all in withApiAuth: any error from auth, rate limiting or the handler is logged with method and path and answered with { data: null, meta: {}, error: "Internal server error" } (status 500). This covers every v1 route. No stack or SQL goes in the body.
  • Update contact (v1 PUT): changing the email to one another contact in the list already has now answers 409 instead of 500.
  • Internal create contact (dashboard): duplicate detection looked for unique/duplicate in err.message. drizzle-orm 0.45 wraps driver errors in DrizzleQueryError, whose message is the failed SQL, so the check never matched and dashboard duplicates also became 500s. New lib/db/errors.ts isUniqueViolation() checks SQLSTATE 23505 on the error or its cause.
  • npm test now runs test files one at a time (--test-concurrency=1), since database test files share one database. CONTRIBUTING updated.

Other v1 write routes checked

  • POST /lists/{id}/contacts/bulk: already upserts with onConflictDoUpdate, so it has no duplicate 500. One separate problem: if the same email appears twice in one batch, Postgres rejects the whole batch ("cannot affect row a second time") and the route counts all of it (up to 500 rows) as skipped. Not changed here.
  • POST /suppressions and /suppressions/bulk: already use onConflictDoNothing.
  • POST /lists and /campaigns: no unique constraints.
  • A listId that is not a uuid makes Postgres raise 22P02. That is now a JSON 500 instead of an empty one, but still a 5xx, so the client would retry it. Not changed here.

Tests

New test/v1-contacts.test.ts (Postgres integration, same pattern as test/email-checker.test.ts):

  • New contact: 201 envelope, one row, one verification job, one audit entry (same as before).
  • Duplicate on a double opt-in list, posted twice: both 409 with the existing contact's id, email and status. Still one row with its original fields, and one confirmation job, one verification job and one audit entry in total.
  • pg-boss send/insert mocked to throw and audit_logs renamed away: still 201, and the contact exists.
  • Non-uuid list id: JSON 500 { data: null, meta: {}, error: "Internal server error" }.
  • 400 and 404 responses unchanged.
  • PUT changing the email to a taken one: 409, and no row changed.
  • Internal POST duplicate: 409 (regression for the drizzle message change).

Run locally against Postgres 17: TEST_DATABASE_URL=... CI=1 npm test: 20/20 pass. Without the fix, the duplicate, catch-all, PUT and internal tests fail (4 of 7). The side-effect test passes without the fix too, which confirms those helpers already swallowed their own errors. npx tsc --noEmit: clean. npm run lint: exit 0, no new warnings.

Deploying

Merging does not deploy anything that I could verify:

  • docker.yml has failed on all of its last 50 runs because the tag ghcr.io/Autter-dev/hedwig-mail has uppercase letters, so no image has been pushed.
  • Railway's GitHub deployments for hedwig / production stop at 3c2b813 (2026-05-07). None of the later commits on main shows a deployment.
  • harbour.autter-logs.com answers through Cloudflare and Caddy.

Someone has to deploy this by hand.

🤖 Generated with Claude Code

POST /api/v1/lists/{listId}/contacts did a plain insert, so a contact already
in the list hit the (list_id, email) unique constraint and the uncaught error
became Next.js's empty-body 500. Integrations retry on 5xx, so those signups
were retried forever.

- Create contact: insert with onConflictDoNothing on (list_id, email) and
  answer 409 in the v1 envelope with the existing contact's id, email and
  status. No confirmation or verification jobs are queued for it.
- Post-insert side effects (confirmation job, verification job, audit log)
  are each caught and logged so they cannot fail a request whose contact was
  already created.
- withApiAuth now catches any error from auth, rate limiting or the handler,
  logs it, and answers a JSON 500 ({ data: null, meta: {}, error }) for every
  v1 route.
- Update contact (PUT): changing the email to one another contact in the list
  has now answers 409 instead of 500.
- Internal create contact: duplicate detection matched 'unique' in the error
  message, but drizzle-orm wraps driver errors and puts the SQL there, so it
  never matched. Check SQLSTATE 23505 on the error or its cause instead
  (lib/db/errors.ts).
- npm test runs test files one at a time, since database test files share
  one database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sagnik11
sagnik11 merged commit b4226cd into main Nov 14, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant