[basit3407]

Problem

In a production end-to-end test with @quranjs/api@3.16.0, a 409 OutOfSyncError from client.auth.v1.sync.pushMutations(...) came back with message "409 " and no useful code (the only code-like value was the Gateway's generic payload.type: "service_error"). isUserSyncOutOfSyncError still detected it correctly.

Root cause

QuranHttpError builds its message as `${status} ${statusText}` and has no code field. Over HTTP/2 there is no status text, so the message is "409 ". The server's code and reason are only in payload (in details.error for the Gateway envelope, in error for the direct backend envelope).

Fix and why it lives in the User Sync facade

The generic cause is shared by every QuranHttpError. I did not change the shared error, for these reasons:

• "<status> <statusText>" is pinned by the HTTP error contract tests (test/http-error.test.ts), and the content-scope 403 hint is appended to it (test/content-scopes.test.ts matches ^403 Forbidden\. ...). Changing every error's message is a wider behavior change than a patch should make.
• App State already follows the same approach: QuranHttpError stays generic and a domain helper (getAppStateErrorCode) reads the service code from the payload.

So createUserSyncFacade now passes any error from /v1/sync through withUserSyncErrorDetails, which updates the same QuranHttpError in place:

• code is set from details.error.code (Gateway) or error.code (backend).
• : <message> is appended to the trimmed base message. It uses the service message, then the top-level message. If neither exists and the error is an OutOfSyncError, it uses Out of sync: lastMutationAt is stale; pull and retry.
• Errors with no service code, and errors that aren't QuranHttpError, are left unchanged.

instanceof, status, headers and payload are untouched. isUserSyncOutOfSyncError is unchanged and still returns false for UniqueViolationError 409s. pullAllMutations restart logic is unaffected. UserSyncOutOfSyncError gains an optional code?: "OutOfSyncError", which is an additive change.

Response	Before	After
Gateway 409 OutOfSyncError, no statusText	"409 ", no code	"409: Invalid lastMutationAt, please re-sync your data and try again.", code: "OutOfSyncError"
Backend 409 OutOfSyncError, no statusText	"409 ", no code	same as the Gateway row
Backend 409 OutOfSyncError with no message	"409 ", no code	"409: Out of sync: lastMutationAt is stale; pull and retry.", code: "OutOfSyncError"
Gateway 409 UniqueViolationError	"409 Conflict"	"409 Conflict: You already have a collection with this name", code: "UniqueViolationError"

Tests

A new case in packages/api/test/user-sync.test.ts covers message and code for both envelopes and for the no-message default. It also checks that UniqueViolationError and errors without a code behave as described, and that detection results are unchanged. It uses an injected fetch because MSW fills in a default statusText, which would hide the "409 " case.

Local checks: Prettier on changed files, tsc --noEmit (typecheck), and eslint for packages/api are clean, and test/user-sync.test.ts passes (10/10).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-05T03:42:05.838888Z	d5042fe	PR opened
🔒 Security Review	✅ Completed 2026-11-05T03:43:21.985193Z	d5042fe	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

size-limit report 📦

Path	Size
dist/index.min.js	8.24 KB (0%)
dist/index.min.mjs	8.21 KB (0%)
dist/server.min.js	18.58 KB (+1.05% 🔺)
dist/public.min.js	10.99 KB (+1.79% 🔺)