Why failures go unrecorded
Measurement plans start from goals, so the events that get built are the ones that mark progress: a product viewed, an item added, a purchase, a lead. Failures are nobody's goal. They sit in different teams' corners, each partly handled by a different guide on this site, and none of those guides records them together:
| Failure | Where it is handled today | What analytics usually sees |
|---|---|---|
| A page that does not exist | The soft not-found errors page makes the template return the right status codeThe numeric code a web server returns with every response, saying whether the request succeeded, was redirected or failed and why. for search engines | A page view with the not-found page's title, if the tag is on that template at all |
| A payment or address lookup that fails | The checkout optimisation guide sets how the checkout should recover | Nothing, or a second view of the payment step |
| A search that returns nothing | The site search tutorial adds a results count to the search event | The search, with or without that count |
| A product that cannot be bought | Merchandising and stock systems | A product page view like any other |
| A form that rejects an entry | The form tracking tutorial's form_error event | The error, by field, if that tutorial has been built |
The result is that a failure surfaces only when it is large enough to move a headline number. The sudden conversion drop page lists a failing checkout among the causes of a fall in conversion rate, and by the time that fall is noticed the failure has been costing sales for days. A failure event turns each of these into a line that can be read every week, and a weekly line with an owner is what gets fixed. The opposite fault, enquiries that reach the inbox or the CRM while GA4 records fewer, is a tracking failure rather than a site one, and the page on GA4 not tracking form submissions diagnoses it.
Before you start
- The data layer guide. The data layer guide explains pushes, the
eventkey, the merging behaviour that leaks old values into new pushes, and the contract table every push here becomes a row of. - The events guide. The events and parameters guide explains custom events, why a parameter must be registered as a custom definition before reports can use it, and why high-cardinality values collapse into an "(other)" row. Its documented limits are in the Google Analytics help centre; read them there.
- The tracking plan, as the tracking plan guide describes it, open at a new version.
- A developer who can change the page templates, the checkout's response handling and the search and listing pages.
- The GA4 configuration in the container and a property role that can register custom definitions, with the building blocks in the tags, triggers and variables guide to hand.
- Preview mode working on the site, including the checkout, following the debugging tutorial, and a test card or test mode the payments team approves.
The steps
List the places a visit can fail
Walk the site with the people who run it and write down every point at which a visitor can try to do something and be told no. The usual list: the not-found template, server error pages, the payment step, address or postcode lookup, discount code entry, search results, filtered category listings that can come back empty, product pages for items out of stock or withdrawn, account sign-in and password reset, and booking or delivery slot selection. For each, note what the visitor sees, which system decides that the action failed, and who owns that system. Ask customer service which complaints they hear most: failures that nobody measured are often the ones they hear about every week. The list is the scope; anything left off it stays invisible.
Agree an error vocabulary in the tracking plan
Choose one custom event name for every failure outside forms, such as
site_failure, and a pair of event parametersA named value sent with an analytics event that describes it, such as a page location, form name or item price.: a failure type and a failure location. The type comes from a short controlled list, such aspage_not_found,server_error,payment_failed,address_lookup_failed,code_rejected,listing_emptyandproduct_unavailable. The location is the template or step where it happened, such ascheckout_paymentorproduct_page, again from a fixed list. Where a type needs one more distinction, add a reason parameter with its own fixed values; for payments that means the site's own categories, such as a decline against a technical failure, never a provider's code or message. Write each value, its meaning and its owner into the plan. Keep the lists short enough that a weekly table fits on one screen; a vocabulary nobody can read at a glance will drift.Specify the data layer push for each failure
Write one row in the data layer contract for each type: the moment the push is sent, the keys and the allowed values. The push carries only controlled values. Nothing the visitor typed goes into it, which rules out search terms in this event, the address entered, a discount code and any message that might echo an entry; the guide to keeping personal data out of analytics explains why typed values leak more often than anyone expects. A payment failure push looks like this:
window.dataLayer = window.dataLayer || []; window.dataLayer.push({ event: "site_failure", failure_type: "payment_failed", failure_location: "checkout_payment", failure_reason: "declined" });Every failure push should state all its keys, setting any it does not use to a fixed empty value, because the data layer guide's merging behaviour means a key left out keeps the value from the previous failure.
Add the push to the not-found template
Ask the developers to render the push on the not-found template itself, after the context push and before or with the page view, so it fires once per not-found response. The address that failed is already part of the page view, so the push needs no copy of it. Do the same on the server error template if the site has one that can still load the container. Check with the SEO owner that the template returns the right status code; that is the soft not-found page's subject and a separate fix, but the two are often made in the same release. A not-found event that fires on any page whose title happens to contain the word "error" is a stopgap, not a measurement.
Record payment and checkout failures when the site confirms them, not on the click
A click on the pay button is an attempt. The failure is known only when the payment response or the checkout's own validation says so, and that is where the push belongs: in the code that handles the response and shows the visitor the failure message. The data layer guide makes the same point for successes, and it applies with more force here, because a push on the click records a failure for every attempt, including those that then succeed. Do the same for address lookup that finds nothing, discount codes the checkout refuses and delivery slots that can no longer be booked. Map the response to the site's own reason values in that code, so the container never sees a raw provider response.
Record empty results and unavailable products
For site search, check whether the search event already carries a results count, as the site search tutorial builds it. If it does, read empty searches from that count and do not send a second event for the same search; if it does not, add the count there rather than here, so search stays in one event. For category and filter listings that come back empty, push
listing_emptywith the listing's location. For product pages, pushproduct_unavailablewhen the page renders an item that cannot currently be bought, with the reason from a fixed list such as out of stock or withdrawn. Product identifiers can travel with the e-commerce item data the site already sends; they do not belong in a registered failure dimension.Build one event tag and register only the parameters reports need
In the container, create data layer variables for each failure key with a default value, a custom event trigger on
site_failureand one GA4 event tag that sends the event with its parameters. In the property, register the type, the location and the reason as event-scoped custom dimensions, because the events guide is clear that an unregistered parameter never reaches a report. Register nothing else. Any parameter with many distinct values, such as an address or an identifier, has high CardinalityThe number of distinct values a dimension or field holds; high-cardinality dimensions, such as page paths with IDs, can exceed report row limits. and would collapse into "(other)" in standard reports, which is why the vocabulary is controlled in the first place. A failure event is not a key event; leave it unmarked. The custom dimensionsA GA4 reporting field created by registering an event, user or item parameter so it appears in reports and explorations. start empty, because registration is not retroactive.Prove every push in preview and DebugView, including the cases that must not fire
Run each failure in preview with GA4 DebugView open and read the event and every parameter. Visit a made-up address: one
page_not_found. Pay with the test card set to fail: onepayment_failedwith the right reason. Then prove the silences, which matter as much. A payment that succeeds sends no failure. A payment that fails and then succeeds on retry sends one failure and one purchase. A search with results sends nothing from this event. A product in stock sends nothing. Reloading a not-found page sends one event per load and no more. Read the parameters for anything a visitor typed. Repeat with analytics consent refused. Record the results against the tracking verification checklist and publish with a version note.Set a weekly read and an owner for each kind of failure
Build a free-form table in GA4 explorations with the failure type and location as rows and weeks as columns, with page path and session source beside the not-found rows, and add the line to the weekly report. Give every type an owner in the tracking plan: developers for server errors, the SEO owner for not-found pages reached from search and links, the checkout owner for payment and lookup failures, merchandising for empty listings and unavailable products. Read each line against its own history, not a borrowed benchmark: the guide to reading small numbers and the control charts framework set limits from a metric's routine movement so a quiet week does not raise an alarm. A rise that crosses the limits goes to its owner; a failure that is visibly hurting live customers follows the live ad and page error response SOP. The failure lines also join the weekly checks in the data quality guide, where a line that falls to nothing overnight usually means the push broke, not that the site was fixed.
A sewing spares shop counts its failures (illustrative)
Zevlonia Sewing Spares adds one failure event
Zevlonia Sewing Spares, an invented online shop selling parts for vintage sewing machines, adds site_failure with
failure_type, failure_location and failure_reason, and registers the 3 parameters. Its search event already carries
a results count. The first 4 weeks:
| Failure | Weekly average | What the read showed | Owner and action |
|---|---|---|---|
page_not_found | 410 | 70% of them were addresses in a discontinued bobbin range, almost all from an old forum post | SEO owner: redirects to the current range |
payment_failed | 95, up from 30 before a checkout change | 80% were technical, all after the new address form went live | Checkout owner: a field the payment step expected was being sent empty; fixed in 2 days |
| Searches with no results | 260 | Most were model numbers typed with a space or a hyphen | Merchandising: model number synonyms added to search |
product_unavailable | 180 | 12 withdrawn parts still linked from category pages | Merchandising: links removed, alternatives added |
After the fixes the payment line returns to 28 a week and sits inside its control limits, and the weekly report now carries one row per failure type with its owner's initials beside it.
Common mistakes
- Recording the click. A failure pushed on the pay button counts every attempt, including the ones that succeed.
- Provider codes in parameters. Raw codes and messages change, leak detail and fragment the table; map them to the site's own values.
- One event per failure. A different name for each kind scatters the reading and invites inconsistent naming.
- Registering addresses or identifiers. High-cardinality values collapse into "(other)" and fill the definitions.
- Duplicating search. A second failure event for empty searches double-counts what the search event already holds.
- Replacing form_error. Forms already have their own event; fold them into the weekly read instead of rebuilding.
- Testing only the failures. Without proving the silences, a success can quietly send a failure too.
- No owner. A failure line that belongs to nobody is read once, admired and forgotten.
- Reading against a benchmark. Limits come from the site's own history, not from another site's error rate.
The Tag Manager hub lists the other guides in this section, including the form, data layer and debugging tutorials this page builds on.
