Docs Troubleshooting

Troubleshooting

Diagnose and fix common sync issues.

Common Error Codes

When a sync fails, the audit log shows an error code and message. Here are the most common ones and what to do about them.

Code Meaning Action
401 Authentication expired Re-authorize the connection in Settings → Connections.
429 Rate limit exceeded Automatic. LedgerPort backs off and retries with exponential delay.
502 Bad gateway (upstream down) Transient. Usually resolves within minutes. Auto-retried.
422 Validation error Check the error detail — usually a missing mapping or invalid field value.
409 Conflict / duplicate Transaction already exists at destination. LedgerPort skips to prevent dupes.

All error details including the full request/response payload are available in Dashboard → Audit Log.

Missing SKU Mappings

The PRODUCT_NOT_FOUND error means an order contains a product that doesn’t have a corresponding item in your accounting software.

Why This Happens

  • A new product was added to your store but hasn’t been created in QuickBooks/Xero yet.
  • The SKU in your store doesn’t match the item name or SKU in your ledger.
  • A product variant (size, color) is treated as a separate item in the accounting system.

How to Fix

  1. Go to Mappings → Products.
  2. You’ll see a list of unmapped products highlighted in amber.
  3. For each, either map it to an existing item in your ledger or let LedgerPort auto-create it.
  4. Click Retry Failed to re-process the affected orders.

Pro tip: Enable Auto-Create Products in Settings to have LedgerPort automatically create new items in your accounting software when unmapped products are encountered.

Connection Timeouts

A timeout means LedgerPort couldn’t reach your platform’s API within the expected window. This is almost always transient.

Automatic Recovery

LedgerPort uses exponential backoff for all retries. After a timeout, it waits 5 seconds, then 15, then 45, up to a maximum of 5 minutes between attempts. Most timeouts resolve on the second or third retry.

If the Problem Persists

  • Check your platform’s status page (e.g., status.shopify.com) for ongoing incidents.
  • For self-hosted WooCommerce, verify your server isn’t rate-limiting API requests.
  • Try disconnecting and reconnecting the platform in Settings → Connections.

The dashboard shows a Connection Health indicator for each linked platform. Green means healthy, amber means intermittent issues, red means the connection needs attention.

Duplicate Entry Prevention

LedgerPort is idempotent by design. Re-syncing the same data — whether triggered manually, by a retry, or by a webhook replay — will never create duplicate entries in your accounting software.

How It Works

Every synced transaction carries a unique fingerprint based on the source order ID, line item hash, and timestamp. Before writing to your ledger, LedgerPort checks whether a matching entry already exists.

  • If a match is found, the sync is skipped and marked as Already Synced.
  • If the data has changed (e.g., an order edit), LedgerPort applies the diff instead of re-creating.
  • If no match is found, a new entry is created normally.

This means you can safely click Retry Failed or Sync Now without worrying about duplicates.