---
title: Export failures
description: Why a batch lands in failed_export — connector state, missing vendors or accounts, duplicate bills, validation rejections, one company of several failing — and how to retry safely
section: Troubleshooting
order: 32
---

# Export failures

An export that fails is annoying and it is also the safe outcome. The alternative, in a product that posts to a general ledger, is a bill that appears twice or against the wrong account, and that costs considerably more to unpick than a red row on a screen.

![Export history with a failed batch expanded, showing the per-invoice rejection reason and a retry control.](/screens/exports.png "A failed batch names the cause per invoice. Nothing in a failed batch posts, so a retry cannot double-post.")

This page covers what makes an export fail, how to tell which cause you have, and how to retry without posting anything twice. It assumes you are a controller or an admin, because posting and connector management are their permissions.

## Where to look first

The exports screen lists batches with their status and, on a failed batch, the reason recorded against it. Above the list, a "needs attention" summary gathers the individual invoices that are parked across recent failed batches, each with its own reason.

Read the item-level reasons before the batch-level one. A batch that says some of its bills need attention is a summary; the invoice rows underneath say what is actually wrong, and different invoices in one batch can fail for different reasons.

## Cause 1: the connector is not connected

Connectors are in one of three states.

| State             | Means                                                                      | Fix                  |
| ----------------- | -------------------------------------------------------------------------- | -------------------- |
| `connected`       | Working                                                                    | —                    |
| `action_required` | The grant is no longer valid — usually an expired or revoked authorization | Reconnect QuickBooks |
| `disconnected`    | No connection at all                                                       | Connect it           |

Nothing can post to a connector that is not connected, so the whole batch fails rather than some of it. This is the most common export failure and the least interesting one: authorizations expire, somebody changed the QuickBooks password, or a colleague disconnected the app while tidying.

Reconnecting is an admin action. There is a connection test on the connector that calls QuickBooks with the stored credentials and reports what came back, which is the quickest way to confirm you have fixed it before you retry forty bills. See [connecting QuickBooks](/docs/connecting-quickbooks).

One edition-level case belongs here rather than under validation: not every QuickBooks Online edition includes Accounts Payable. If the connected company cannot hold bills at all, the connection is recorded as such and no amount of retrying will change it. The fix is on the QuickBooks side.

## Cause 2: a vendor or account QuickBooks does not have

InletAP maps your local records to their counterparts in the ledger — vendors, accounts, classes, departments, tax codes. If an invoice is coded to something with no counterpart, that invoice parks.

This happens for three reasons:

- The vendor is new and has never existed in QuickBooks.
- Somebody renamed or merged an account in QuickBooks, and the mapping now points at nothing.
- The reference data was synced before the account existed.

The fix is to re-sync reference data from the connector and then map the record by hand where the automatic match cannot find it. Both are admin actions on the connector. An unmapped vendor is the one export failure a customer can fix entirely without us, so it gets its own notification rather than being one line inside "six bills need attention" — and it is keyed on the vendor, so ten invoices from the same missing vendor are one email and one fix.

## Cause 3: the bill is already in QuickBooks

If a bill with the same document number already exists in the target company, QuickBooks refuses the create. That is usually correct: either the invoice was posted from InletAP before, or somebody entered it by hand.

InletAP looks for the bill that already exists rather than forcing a second one. Each export item records the external identifier of the bill it produced, so the question "did this actually post" has an answer on the document rather than being a matter of opinion.

If the duplicate is legitimate — two genuinely different invoices carrying the same number, which some vendors manage — the invoice number needs to differ before it will post.

## Cause 4: the ledger rejected the data

QuickBooks validates what it is given, and rejects what it will not accept. Common shapes:

- A required value the company's settings demand and the invoice does not carry — a tax code on a company that tracks sales tax, for example.
- A class or department on a company that does not track them.
- A posting date inside a closed period.
- A value outside a limit the ledger enforces.

We do not print invented error codes here, because the exact text and code come from QuickBooks and change with their platform. What InletAP records is the reason the ledger gave, against the item that failed, together with the correlation identifier that Intuit support asks for if the problem turns out to be at their end.

The fix is on the invoice: correct the coding, the date or the missing value, and retry. A validation rejection will not resolve itself, so InletAP parks the item rather than retrying it endlessly and burning your ledger's rate limit.

## Cause 5: one company took it and another did not

An invoice split across ownership entities with separate QuickBooks companies posts as one bill per company. Those posts are independent, so they can also fail independently: two bills posted, one parked. The document's status is then `partially_exported`.

The export screen shows one row per company, each with its own amount, its own outcome and, where it posted, a link to the bill. Read those rows rather than the batch summary; the company that failed usually failed for one of the ordinary reasons above, and the interesting detail is which company.

The most common cause is worth knowing in advance: **reference data is mapped per company.** A vendor, an account or a class that exists in your main company does not exist in the second one until it is mapped there. So a fan-out often fails first in the newest company, for an unmapped vendor, and the fix is on that company's connector.

Retry is aimed at the company that failed. The bills that already posted are not re-sent, and each bill carries its own request identity, so a retry cannot duplicate a posting that already succeeded. When the parked target goes through, the document moves to `exported`.

If you would rather not retry, the honest fallback is to enter the missing bill by hand in that company and note it — but check the amount against the row on the export screen, because that figure is the company's exact share of the split, to the cent. See [multi-entity QuickBooks](/docs/multi-entity-quickbooks).

## What retries automatically and what does not

Transient conditions — a timeout, a rate limit, a temporary server error at the ledger — are retried on a backoff without you doing anything. Rate limiting in particular is waited out rather than hammered.

Everything else is parked for a person, because it needs a change before it can succeed. This is the distinction worth understanding: a batch you can see sitting in `failed` has already finished trying.

## Retrying safely

Retry is available on a failed batch. It is a replay of the same logical post, not a new one — the request identity is preserved so that a post which actually reached QuickBooks returns the original bill instead of creating a second.

Some rules follow from that:

- A batch that is still `pending` or `processing` cannot be retried, because a run is either queued or in flight and a second one would work through the same items alongside the first.
- A `succeeded` batch cannot be replayed. There is nothing to gain and one obvious thing to lose.
- Retrying twice in quick succession queues one retry. The second click is told the batch has already been re-queued.

Fix the cause first, then retry. A retry against an unchanged validation failure produces the same failure, more slowly.

## CSV and SFTP exports

A CSV export has far less to go wrong: there is no remote ledger to reject anything. Failures here are usually a delivery problem rather than a data problem — an SFTP destination refusing the connection or the credentials.

The file itself remains downloadable from the batch, so a delivery failure never means a lost close. You can take the file and import it by hand while you sort out the destination. See the [exports reference](/docs/exports-reference).

## What is recorded either way

Every attempt is written to the audit trail with its outcome, and each batch keeps its attempt history. A bill posted late after two failures is distinguishable from a bill posted twice, which is precisely the distinction your auditor will care about and nobody else will ever think about again. See the [audit trail](/docs/audit-trail).

## Still stuck

Write to support@inlet-ap.com with the batch reference and the invoice that failed. If the ledger returned a correlation identifier we will have it against the item, and it is the fastest route to an answer when the problem is genuinely at the ledger's end.