503 vs. 504 from QuickBooks Desktop: Which Requests Are Safe to Retry
- quickbooks api retry 503
- handle 504 timeout quickbooks
- retry-after 429 api
- safe retries quickbooks desktop

Quick answers
- Is a 503 AGENT_OFFLINE safe to retry? Yes — it means the request was never delivered to QuickBooks, so retrying it cannot double-apply anything.
- Is a 504 AGENT_TIMEOUT safe to retry? Not blindly — the request was sent and the answer never came back, so a write may have applied; re-query before you retry it.
- What does 429 RATE_LIMITED tell me? It carries a
Retry-Afterheader plusRateLimit-*headers; wait the indicated interval rather than backing off on a guess. - Which of these need idempotency protection? Only 504 and any other outcome-unknown case. 503 and 429 are known-not-applied, so a plain retry is correct.
- Do batch requests follow the same rules? The same semantics apply, but per item — a batch response can carry a mix of succeeded and failed items, and you retry individually.
The only question that matters in a retry policy
Every retry decision reduces to one question: did the write happen?
Not "was there an error." Not "is this transient." Errors that are permanent (a validation fault, a missing account) are easy — you never retry them. Errors that are transient are easy in the other direction — you retry them. The hard category is the one where the transport failed after the request was handed off, and you genuinely do not know whether the ledger changed.
HTTP conflates these. A 500 from a generic web service tells you almost nothing about outcome. The useful thing about the error contract in front of QuickBooks Desktop is that the status codes are assigned by where in the chain the request died, which is exactly the information a retry policy needs.
Here's the chain. Your service calls the REST API. The API hands the request to an agent process that has a connection to the company file. The agent talks to QuickBooks via qbXML. QuickBooks does the work and answers back along the same path.
Two things can go wrong in transport, and the distinction between them is the whole post:
- The agent isn't there to hand the request to. Nothing was sent. 503 AGENT_OFFLINE.
- The agent took the request, and no answer came back in time. Something was sent. 504 AGENT_TIMEOUT.
503 AGENT_OFFLINE: nothing was sent
A 503 with code AGENT_OFFLINE means the agent that bridges to the company file wasn't connected when your request arrived. The request was never delivered to QuickBooks.
That makes it the friendliest failure in the system. There is no partial state to reason about, no invoice that might exist, no customer that might have been created with the name you're about to reuse. The request did not happen. Retry it as-is, including writes, including POST /invoice with no idempotency key, and the worst case is you wait.
Common causes, in rough order of how often you'll hit them:
- The company file isn't open yet, or the machine hosting it is between sessions.
- A hosted environment (Rightworks, a Citrix or RDS farm) logged the session out overnight and nothing has woken it back up. If your integration runs against hosted QuickBooks, the overnight-idle behavior is worth reading about on its own — we went through the session model in Integrating with Multi-User and Hosted QuickBooks Desktop.
- Someone rebooted the workstation, or an update is applying.
The practical implication for scheduling: your first job of the morning is the one most likely to see 503. Build the retry window around that reality. A nightly sync that gives up after three attempts at 30-second intervals will fail every time the bookkeeper is five minutes late opening the file. Three attempts over fifteen minutes is a better shape for the same job.
504 AGENT_TIMEOUT: sent, outcome unknown
A 504 with code AGENT_TIMEOUT means the opposite: the agent received your request and no response came back within the timeout. The request reached the agent. Whether QuickBooks applied it, you do not know from the response.
This is the case that produces duplicate invoices in production, because it is also the case where a naive if (status >= 500) retry() policy feels correct. It isn't. Treat 504 as outcome unknown, and split your handling by method:
Reads. Retry freely. A GET or a query that times out costs you nothing to repeat. If your read reliably times out — a query over thousands of rows, a report pull — the fix is usually pagination or a narrower filter, not a longer timeout.
Writes. Do not retry until you've re-queried. The sequence is:
- Catch the 504. Do not retry.
- Query for the object you were trying to create or modify, using a field you control — your own document number, a
DocNumber, a memo you stamped, an external reference. - If it exists and matches what you intended, record the ID and treat the operation as successful. You're done.
- If it doesn't exist, retry the original write.
- If it exists but looks half-right, stop and surface it. That's a human decision, not a retry decision.
Step 2 is the step people skip, and it's the step that requires planning before the timeout. You can only re-query for something if you wrote it with a value you can search on. For invoices, DocNumber is the obvious handle:
GET /v3/company/{realmId}/query?query=
select * from Invoice where DocNumber = 'EXC-10427'
If you're generating DocNumber on the QuickBooks side and letting it auto-increment, you have nothing to search on after a timeout. Assign it yourself. We walked through the broader version of this in Syncing Invoices to QuickBooks Desktop Over a REST API — the short version is that a stable external key you control is worth more than it looks until the first time a request times out.
Why does Desktop time out more than QBO does in the first place? Because the work is happening in a single-threaded desktop application that may also be serving a human. A long report, another user running a rebuild, a large Add against a file with a lot of history — any of these can push a single request past the timeout. It's not a failure mode you can eliminate, so it's one you plan for.
429 RATE_LIMITED: wait the amount you're told to wait
A 429 with code RATE_LIMITED means the request was rejected before reaching QuickBooks, which puts it in the same safe-to-retry category as 503. The difference is that the response tells you exactly how long to wait.
Two things to read:
Retry-After— seconds to wait before the next attempt.RateLimit-*headers — the current limit/remaining/reset picture.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 500
RateLimit-Remaining: 0
RateLimit-Reset: 30
Honor Retry-After over your own backoff curve. If the header says 30 and your exponential backoff says 2, sleeping 2 seconds just burns another request and resets the clock. The useful pattern is sleep(max(retryAfter, backoff)).
The RateLimit-Remaining value is more interesting than it looks for batch jobs: if you're reading it on every response, you can slow a bulk import down before you start getting 429s, which keeps throughput smoother than sprinting into a wall and recovering.
A retry policy, in about forty lines
Keyed on status first, then on the error code, with the outcome-unknown case routed somewhere it can't do damage:
type Outcome = "retry" | "verify-then-retry" | "fail";
interface ApiError {
status: number;
code?: string; // e.g. "AGENT_OFFLINE"
retryAfterSeconds?: number; // parsed from Retry-After
}
const MAX_ATTEMPTS = 5;
function classify(err: ApiError, isWrite: boolean): Outcome {
switch (err.status) {
case 503:
// AGENT_OFFLINE: never delivered to QuickBooks. Always safe.
return "retry";
case 429:
// RATE_LIMITED: rejected before QuickBooks saw it. Safe.
return "retry";
case 504:
// AGENT_TIMEOUT: sent, answer never came back. Outcome unknown.
return isWrite ? "verify-then-retry" : "retry";
default:
// 4xx validation faults and anything else: do not retry.
return "fail";
}
}
function delayMs(err: ApiError, attempt: number): number {
const backoff = Math.min(2 ** attempt * 1000, 60_000);
const jitter = Math.random() * 500;
const floor = (err.retryAfterSeconds ?? 0) * 1000;
return Math.max(backoff, floor) + jitter;
}
And the driver, with the verify hook as a required argument for writes so you can't forget it:
async function withRetry<T>(
send: () => Promise<T>,
opts: { isWrite: boolean; verify?: () => Promise<T | null> },
): Promise<T> {
for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
try {
return await send();
} catch (e) {
const err = e as ApiError;
const outcome = classify(err, opts.isWrite);
if (outcome === "fail") throw err;
if (outcome === "verify-then-retry") {
if (!opts.verify) throw err; // no way to check: escalate, don't guess
const existing = await opts.verify();
if (existing) return existing; // it did apply
}
await sleep(delayMs(err, attempt));
}
}
throw new Error("retry budget exhausted");
}
The design choice worth copying: verify is not optional in practice. If a write path can't answer "did this already happen," withRetry refuses to retry it and raises instead. That turns a silent duplicate-invoice bug into a loud operational one, which is the trade you want.
The batch variant: same rules, one level down
Batch requests change where you apply the logic, not the logic itself.
A batch is a list of operations submitted together, and each item gets its own result. A batch request can come back 200 OK overall with a mix of succeeded items and failed items inside it — the HTTP status describes the batch envelope, not the ledger. So:
- If the whole batch fails with 503, nothing in it was sent. Resubmit the whole batch.
- If the whole batch fails with 504, any subset of its items may have applied. Verify before resubmitting — and verify per item, not per batch.
- If the batch returns 200 with per-item faults, retry only the failed items, after fixing whatever caused the fault.
Run the classification over response.BatchItemResponse[], matching on bId, and build a new batch from only the items that need another attempt:
const failed = response.BatchItemResponse.filter(r => r.Fault);
const retryable = failed.filter(r => isRetryableItem(r.Fault));
if (retryable.length) {
await submitBatch(
retryable.map(r => originalById[r.bId]),
);
}
The failure mode here is resubmitting a whole batch because two of its fifty items failed, which re-applies the forty-eight that worked. The reason this is worth repeating is that batches on Desktop don't roll back as a unit — there's a longer treatment in QuickBooks Batch Requests Are Not Transactions, and the per-item response shape is documented in the batch guide.
What this looks like in practice
Say ExampleCo pushes invoices to a Desktop company file nightly at 2:00 AM, and Pat Owner closes QuickBooks before leaving.
- 2:00 AM, first request: 503 AGENT_OFFLINE. Nothing sent. The job backs off and keeps trying for twenty minutes while a scheduled task wakes the session.
- 2:03 AM, session up, invoices start flowing. One of them is a 400-line job invoice and the request takes too long: 504 AGENT_TIMEOUT. The job queries
DocNumber = 'EXC-10427', finds it — it did apply, QuickBooks was just slow answering — records the ID and moves on. No duplicate. - 2:05 AM, the loop is going faster than the limit allows: 429 with
Retry-After: 30. The job sleeps 30 seconds and continues.
Three different statuses, three different correct behaviors, zero duplicates. The policy did all of it without a human.
Where to check the specifics
The authoritative list of status codes and error codes — including the ones this post doesn't cover, like validation faults and auth failures — is the error codes reference. Codes are stable strings; branch on the code, not on the human-readable message, which can change.
If you're mapping these back to what QuickBooks itself returned, the underlying qbXML status code and HRESULT surface in the fault detail. Decoding QuickBooks Desktop Errors covers how Desktop's native error vocabulary maps onto QBO-style faults, which is useful when you're deciding whether a 4xx is a your-data problem or a their-file problem.
And if you want to exercise this against something real before wiring it into production, the sandbox speaks the same error contract.
FAQ
Why does the first request of the day return 503 AGENT_OFFLINE on hosted QuickBooks?
Hosted environments commonly log sessions out after a period of idleness, so by the time your overnight job runs there may be no live connection to the company file. The 503 means your request was never delivered, so it's always safe to retry — just size the retry window to cover however long the session takes to come back up, which is minutes rather than seconds. Hosted QuickBooks on Rightworks covers the connection model in more detail.
Can I just use an idempotency key instead of re-querying after a 504?
If your write path has a natural idempotency handle — a DocNumber you assign, an external reference you stamp into a memo field — then the re-query is the idempotency check, and it's the cheapest one available. The important part is that something unique and searchable goes in before the request is sent, not after.
Should I retry a 500?
No, not automatically. 503, 504, and 429 are the statuses that carry outcome information about the transport; a 500 doesn't tell you where it failed. Log it with the error code, surface it, and look at the code on the error-codes reference before deciding whether that specific failure is worth a retry.
How long should my total retry budget be?
Longer for scheduled batch jobs, shorter for anything a human is waiting on. A nightly sync can reasonably spend 15–20 minutes absorbing 503s, because the alternative is a failed run. A user-facing "save to QuickBooks" button should give up in well under a minute and show an actionable message instead of spinning.
Do these same semantics apply if I'm pointing an existing QBO integration at Desktop?
The request and response shapes match QBO, but 503 AGENTOFFLINE and 504 AGENTTIMEOUT are Desktop-specific conditions you won't have hit against Online, so a QBO-tuned retry policy usually needs this one addition. The rest of the porting work is covered in the checklist for pointing your QBO integration at Desktop. If you want to watch these codes come back from a live endpoint, the quickstart gets you issuing requests in a few minutes.