How to read a delivery log

Nobody reads a delivery log for pleasure. You open it because a row is missing, a customer says they contacted you, or somebody noticed the sheet looks thin.

That is unfortunate timing, because interpreting it is easiest when you are calm and have seen a normal one. A log full of successes looks boring, and the boring version is what teaches you what abnormal looks like.

It is worth ten minutes on an ordinary day. Open it, look at a successful submission, and note how many entries a healthy delivery produces and how quickly.

Then when you next open it under pressure, you are comparing against something rather than guessing.

A delivery log is a record of attempts, not of submissions. That distinction explains most of the confusion people have with it.

One submission can produce several entries: the initial attempt, a retry after a failure, another retry, and eventually a success. Reading it as one line per lead will make it look as though you received far more enquiries than you did.

Each entry typically carries a timestamp, the submission it belongs to, an attempt number, an outcome, and whatever the destination said if it said anything.

The last field is the one that matters most and is usually the least readable, because it contains an error from an API that was written for developers.

That is worth tolerating rather than wishing away. A summarised, friendly error is easier to read and frequently discards the one detail that identifies the cause, so a log that quotes the destination verbatim is more useful than a tidy one. Where an error is genuinely impenetrable, it is usually searchable, because somebody else has hit the same string from the same kind of integration.

The vocabulary is small. Queued means accepted and waiting. Processing means an attempt is in flight. Delivered means the destination confirmed the write. Failed means this attempt did not succeed but the item will be retried. Permanently failed means attempts have been exhausted and a person needs to intervene.

The important pair is failed against permanently failed. The first is normal and self-healing; a transient failure at a busy moment is unremarkable and resolves itself.

The second is the one that costs you leads if ignored, because nothing further will happen without you.

If your log offers a filter, the permanently failed filter is the one to bookmark. It is the only view that reliably contains actionable items.

A healthy submission shows one entry, delivered, within a few seconds of arrival. That is the overwhelming majority of traffic on a working pipeline.

A submission with two entries, one failed and one delivered a few minutes later, is also healthy. It means something upstream had a brief problem and the retry mechanism did its job. This is the system working, not a fault.

A submission with five failures over several hours and then a success tells you there was a real outage somewhere, and it is worth checking whether it correlates with anything else.

None of those require action. Knowing they do not is half the value of understanding the log.

Three patterns are worth recognising on sight.

Many submissions failing at the same moment and recovering together is a destination outage. It is nobody's fault, it is already over, and the only question is whether anything did not recover.

A single submission failing repeatedly while everything around it succeeds is a data problem: something about that specific submission the destination will not accept. An oversized field, an unexpected character, a value that does not fit the column.

Everything failing since a specific moment with no recovery is a configuration or permission problem. Someone renamed a sheet, revoked an authorisation, or deleted a tab. This one is urgent because it will not fix itself and every new submission joins the backlog.

The messages come from the destination and follow a few patterns worth translating.

Anything about authorisation or credentials means the connection needs re-establishing, usually because a token was revoked or a password change invalidated a session. Anything about not found means the target moved, was renamed, or was deleted. Anything about quotas or rate limits means you are sending faster than the destination allows, which is temporary and handled by backoff.

Permission errors are the most misleading, because they often appear long after the change that caused them. A sheet shared differently three weeks ago produces a failure the first time something tries to write to it after the change.

When an error is genuinely opaque, the useful move is to compare a failing submission against a successful one from the same day and look for what differs in the data.

Timestamps answer questions that statuses cannot. The gap between acceptance and delivery is your real latency, and it is worth knowing what normal looks like.

A gap that has been growing over weeks suggests a queue that is not keeping up rather than one that failed, which is a different and quieter problem.

Clustered failures around the same time each day usually point at something scheduled: a backup, a report, a job that saturates something.

And a long gap between the last entry and now, on an item that is not delivered, is the signature of something stuck, which is worth escalating even though nothing has explicitly failed.

The most common real use is answering somebody who says they contacted you and heard nothing.

With a log you can establish whether a submission exists at all. If it does not, the problem is on the page or the person did not actually submit. If it does and was delivered, the row is in your sheet and the failure was human. If it exists and was never delivered, you have found a real fault and you also still have the enquiry.

All three answers are useful and none are available without the log. Without it the conversation is a matter of opinion, and the customer usually wins.

Filter to failures. Look up a specific submission. See every attempt for it. Read the destination error verbatim rather than a summarised version. Retry an item by hand after fixing the cause.

That last capability is the one people discover they need at the worst moment. After you fix a permission problem, the backlog should be replayable without contacting support.

If a service offers a log but no manual retry, its recovery story ends with an email to somebody else, which is a poor position during an incident.

It is a reasonable thing to check before choosing, alongside the questions in what happens when an endpoint goes down.

Open the log now, while nothing is wrong. Find a successful delivery and note the shape. Filter to failures and see whether the list is empty, and if it is not, find out why. Check whether anything is permanently failed and has been sitting there.

That exercise regularly turns up items nobody knew about, usually from a configuration change weeks earlier, and it is the cheapest lead recovery available to most sites.

It pairs well with the other one-minute habit: comparing the number of rows in your spreadsheet against the number of submissions the pipeline accepted for the same period. The log explains individual failures; that comparison tells you whether there is anything to explain at all.

Why does one submission have several log entries?

What is the difference between failed and permanently failed?

Should I worry about occasional failures?

What does an authorisation error mean?

Why did everything start failing at once with no warning?

Can I recover submissions that failed permanently?

How long should log entries be kept?

What should I check on a normal day?