intermediate 2 min answer

A marketplace has three dashboards that each report "active sellers": billing counts sellers with a payment in 30 days (41,000), search counts sellers who edited a listing in 90 days (118,000) and support counts sellers who logged in within 60 days (76,000). A fee-waiver job reads "active sellers" from the search service. What happens, and how do you prevent it?

vocabularynamingcontractsdata definitionsfailure mode
Show the full answer Hide the answer

Second by second

The fee-waiver job was written by the billing team, who read "active sellers" as the 41,000 who paid. It calls the search API, which returns 118,000. The job waives fees for 77,000 sellers who were never meant to qualify, and nothing fails: the API responds, the numbers are plausible and the job completes on time.

Where it amplifies

The error is not noticed at the call. It surfaces at month end as lost revenue. If the average waived fee is 12 dollars a month, 77,000 extra sellers is about 924,000 dollars. A second round of damage follows when the team "fixes" the number by hard-coding 41,000 in the job, so the next definition change breaks it silently again.

What the user sees

Sellers see a fee waiver they did not expect and some find it again after it disappears, creating support contacts. Finance sees a revenue gap with no incident to point at.

What stops it

A mechanism, not a meeting:

  1. One name, one definition. Replace "active seller" with names that carry the rule, such as seller_paid_30d, seller_listing_edit_90d and seller_login_60d.
  2. One owner per definition. Billing owns the first, search the second. A consumer cannot redefine it.
  3. The definition in the interface. The API field name and its documentation state the window and the event counted. A contract test fails when the definition changes.
  4. A glossary page where each term links to its owning service, reviewed when a definition is edited.

What would have to be true to self-heal

Never; this failure does not heal itself because it makes no error. It is only found by someone comparing two numbers.

When this is the wrong answer

For a company of five people who all sit together, a single word with a shared meaning is cheaper than a naming scheme. Vocabulary rules pay once different teams own different systems and a number crosses a service boundary.

Common weak answers

  • "Add monitoring." Monitoring sees an API call succeed. The data is valid, only the meaning differs.

What a strong answer adds

A rule for changing a definition: version the name, run the old and new side by side for a cycle, and list consumers before editing.