OUT-3754: correct duplicate doc number code from 6240 to 6140

[SandipBajracharya]

Summary

Per Intuit docs, QBO error 6140 is "Duplicate Document Number" and 6240 is "Duplicate Name Exists". isQBODuplicateDocNumberError was matching 6240, so the suffix-retry path in webhookInvoiceCreated (OUT-3708) never fired on real doc-number collisions — every collision fell through to a FAILED qb_sync_log.

Swap 6240 → 6140 in the detector, log/breadcrumb strings, JSDoc, and the docNumber-specific tests. References to 6240 that legitimately refer to "Duplicate Name Exists" (customer DisplayName collision guard) or that just use 6240 as a generic fault-code example are left alone.

Code sites

• src/app/api/quickbooks/invoice/invoice.utils.ts — isQBODuplicateDocNumberError
• src/app/api/quickbooks/invoice/invoice.service.ts — resolveAvailableDocNumber JSDoc + catch/retry log + breadcrumb
• src/utils/intuitAPI.ts — _findInvoicesByDocNumberPrefix JSDoc reference
• test/unit/app/api/quickbooks/invoice/invoice.utils.test.ts
• test/unit/app/api/quickbooks/invoice/invoice.service.docNumber.test.ts
• test/integration/quickbooks/invoiceCreated/qboDocNumberCollision.test.ts

Test plan

• npx vitest run --project unit — 165/165 passing
• Integration suite (needs Docker) — defer to CI
• Manual sandbox: trigger a real 6140 in QBO sandbox by enabling "Custom transaction numbers" and reusing a DocNumber; confirm the suffix retry now actually fires (it would not have before this fix)

🤖 Generated with Claude Code

[linear-code]

OUT-3754

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Building		May 19, 2026 10:29am
quickbooks-sync (dev)	Ready	Preview, Comment	May 19, 2026 10:29am

[greptile-apps]

Greptile Summary

This PR corrects a misidentified QBO error code in isQBODuplicateDocNumberError: 6240 ("Duplicate Name Exists") is replaced with the correct 6140 ("Duplicate Document Number"), meaning the suffix-retry path in webhookInvoiceCreated was never actually triggered on real doc-number collisions before this fix.

• invoice.utils.ts: All comparisons (numeric, string, regex) updated from 6240 → 6140 so isQBODuplicateDocNumberError now correctly identifies the right QBO fault.
• invoice.service.ts: JSDoc, inline comments, console.info log, and addSyncBreadcrumb string updated for accuracy; no logic changes.
• Tests: All unit and integration test fixtures updated to 6140, ensuring the corrected detection path is exercised; the remaining 6240 references in the codebase (generic examples and the customer DisplayName guard) are correctly left untouched.

Confidence Score: 5/5

Safe to merge — the change is a targeted one-constant correction backed by the official Intuit documentation and covered by existing tests.

The fix is a straightforward swap of the wrong error code for the correct one across source, comments, and tests. All six changed files are consistent, no logic is restructured, and the remaining 6240 references in the codebase are for an unrelated error (customer DisplayName collision) and are correctly untouched. Unit tests pass at 165/165.

No files require special attention.

Important Files Changed

Filename	Overview
src/app/api/quickbooks/invoice/invoice.utils.ts	Core fix: all 6240 comparisons in isQBODuplicateDocNumberError replaced with 6140 (both numeric and string forms), plus regex literals and JSDoc updated.
src/app/api/quickbooks/invoice/invoice.service.ts	JSDoc, inline comment, console.info log, and addSyncBreadcrumb string all updated from 6240 to 6140; no logic changes.
src/utils/intuitAPI.ts	Single JSDoc comment reference updated from 6240 to 6140; all other 6240 references in the file are generic examples and correctly left alone.
test/integration/quickbooks/invoiceCreated/qboDocNumberCollision.test.ts	Mock error fixture updated to use code '6140' so the integration test now exercises the corrected detection path.
test/unit/app/api/quickbooks/invoice/invoice.utils.test.ts	All unit test fixtures, test descriptions, and assertions updated from 6240 to 6140 across numeric, string, and top-level variants.
test/unit/app/api/quickbooks/invoice/invoice.service.docNumber.test.ts	File-header comments updated from 6240 to 6140; no test logic changes.

Sequence Diagram

sequenceDiagram
    participant WH as webhookInvoiceCreated
    participant RDN as resolveAvailableDocNumber
    participant QBO as QBO API
    participant Det as isQBODuplicateDocNumberError

    WH->>RDN: pre-flight prefix query
    RDN->>QBO: _findInvoicesByDocNumberPrefix
    QBO-->>RDN: existing DocNumbers
    RDN-->>WH: available docNumber

    WH->>QBO: createInvoice(docNumber)
    alt success
        QBO-->>WH: Invoice created
    else QBO returns error
        QBO-->>WH: Error (code 6140 "Duplicate Document Number")
        WH->>Det: isQBODuplicateDocNumberError(err)
        Note over Det: Previously matched 6240 (wrong)<br/>Now correctly matches 6140
        Det-->>WH: true
        WH->>RDN: re-walk once
        RDN->>QBO: _findInvoicesByDocNumberPrefix
        QBO-->>RDN: updated DocNumbers
        RDN-->>WH: new available docNumber
        WH->>QBO: createInvoice(newDocNumber)
        QBO-->>WH: Invoice created (retry succeeded)
    end

Loading

_{Reviews (1): Last reviewed commit: "fix(OUT-3754): correct duplicate doc num..." | Re-trigger Greptile}

[priosshrsth]

@SandipBajracharya I would suggest to use QB_STATUS_CODES constant. So we can do like QB_STATUS_CODE.DUPLICATE_DOC_NUMBER, etc. and in comments instead of vague 6140, we say DUPLICATE_DOC_NUMBER, wdyt?

[SandipBajracharya]

@SandipBajracharya I would suggest to use QB_STATUS_CODES constant. So we can do like QB_STATUS_CODE.DUPLICATE_DOC_NUMBER, etc. and in comments instead of vague 6140, we say DUPLICATE_DOC_NUMBER, wdyt?

Nice suggestion. Thanks

[priosshrsth]

lgtm