Field notes
What counts as usage? Failed requests, retries and late events
Usage contracts price a unit they rarely define. In our example, leaving server errors and duplicate retries out of one month's count removes 2.5% of the events and 15% of the overage bill.
About these field notes. They draw on public discussions with founders, RevOps and billing practitioners in October 2026, prompted by our review of 64 pricing pages. We paraphrase and don't name anyone. The worked example is an illustration we built to show the mechanics, not any company's real figures.
The question we hadn't asked
When we shared our review of 64 usage-based pricing pages, one reader asked about a rule we hadn't scored. Do failed requests count toward usage? And if a request times out and then succeeds on retry, is the customer paying for one request or two? Their suggestion was to put the answer in the sample month of the contract, next to the rollover and overage examples.
Another reader described what an unwritten rule looks like from the customer's side: a surprise overage bill, and a finance team asking why the rule behind it wasn't spelled out anywhere. It wasn't one of the five rules we scored, and in our notes on those 64 pages only one mentions retries at all.
Six things a usage definition should settle
- Errors the vendor caused. Requests that fail with a server error (5xx). Most vendors would say these aren't billable, but few pricing pages say so either way.
- Errors the customer caused. Bad credentials, invalid input, requests rejected for rate limits (4xx). Practice varies. Rate-limited requests (429) deserve their own sentence, because the customer was refused by the vendor's own limit.
- Timeouts where the work was done. The vendor did the work and the customer never saw the result. Is it billed?
- Retries and duplicates. One billable event per request ID or idempotency key, or every attempt? Stripe's meter events, for example, take an
identifierthat Stripe keeps unique for a rolling period of at least 24 hours. A retry that arrives more than a day later may not be caught there, so deduplicate before you report. - Partial work. A streamed response cut off halfway, or a batch job canceled after some records were processed. Billed in full, in part or not at all?
- Timing. Does usage belong to the period it happened in or the period it was received? What's the cutoff, and what happens to events that arrive after the invoice is final? Stripe, again as an example, only accepts meter events timestamped within the past 35 days.
One month of API usage, three definitions
A contract includes 1,000,000 requests a month, with overage at $0.03 a request. The meter recorded 1,200,000 requests this month. Of those, 24,000 (2%) failed with server errors, and 6,000 (0.5%) were duplicates created when clients retried after a timeout.
| Definition of a billable request | Billable | Overage requests | Overage bill |
|---|---|---|---|
| Everything the meter recorded | 1,200,000 | 200,000 | $6,000 |
| Excluding server errors | 1,176,000 | 176,000 | $5,280 |
| Excluding server errors and duplicates | 1,170,000 | 170,000 | $5,100 |
2.5% of the events, 15% of the overage: $900 this month, about $10,800 a year on one contract.
The effect is lopsided because the included allowance doesn't move. As long as usage stays above the allowance, every excluded request comes off the top, so the whole difference lands on overage.
Plus the late events
A further 3,600 requests dated in this month reach the billing system after the invoice is final. There are three ways to treat them:
- Reopen the month: issue a corrected invoice for $108 more. That's accurate, but it means a changed invoice the customer may already have paid.
- Count them in next month's usage: if next month stays inside its allowance, they're never billed at all. $0.
- Add an adjustment line next month, priced at this month's terms: $108, with the original period shown. Nothing already invoiced changes. This is the approach we recommend in append-only true-up ledgers.
It leaks in both directions
Counting the duplicates bills the customer $180 for requests they made once. When their engineers find it, the fix is a credit note and a difficult call. A customer success manager described the cost of those calls in reply to one of our posts: finance owns the invoice, but the CSM owns the relationship, and the CSM is the one the customer trusts less by the end. Leaving late events out loses revenue quietly instead. Either way, the definition gets decided after the fact, by whoever is on the call.
A usage definition to adapt
Something like this, sitting next to the rollover and overage clauses, settles most of the six questions:
"Billable Request" means a request to the API that (a) is authenticated with Customer's credentials, (b) receives a response with either a 2xx status code or a 4xx status code other than 429, and (c) has a request ID not already counted. Requests that receive a 5xx status code, or that time out before a response is returned, are not Billable Requests. Usage is assigned to the billing period of the request's timestamp (UTC). Usage reported after an invoice is issued is billed on the next invoice, as a separate line, at the rates in effect when the usage occurred.
It's a starting point to adapt with your counsel, not legal advice. Change the status codes to fit your API, and add a sentence for partial work if you stream.
Checks to run on last month's usage
- Duplicates. Count events sharing a request ID or idempotency key. Anything above zero in the billed total is an over-bill.
- Error share. What share of billed events had a 5xx status? If the contract excludes them, that share should be zero.
- Period mismatches. Find events whose timestamp falls outside the period they were billed in.
- Late arrivals. Find events received after the invoice date, and check how each one was billed, if at all.
- Tie-out. The billable count in the warehouse should equal the quantity on the invoice, line by line.
Want to know what your invoices are counting?
Send us a sample of usage events, a few redacted contracts and the invoices. We'll recount each period under the contract's definition, including duplicates and late events, and show every difference. Free, within 48 hours of complete files.