What Counts as a Successful API Call for Paid Endpoints

What counts as a successful API call sounds like a settled question until two people try to compare their numbers. For a free endpoint, success usually means an HTTP response with a non-error status. For a paid endpoint, that is only the first of three separate events, and a reliability figure is only useful once you know which of them it counts.

Three successes that rarely get separated

A paid call can succeed or fail at three layers, and each one is recorded by a different system.

• Transport success: the request reached the endpoint and an HTTP response came back with a status that does not signal an error.
• Payment success: the payment the gateway required was accepted and settled, and the buyer was charged once.
• Usable response: the body arrived complete and matches the output contract the provider advertised, so the next step of the workflow can read it.

A fourth question sits above all three: was the answer right? That is result quality, and it belongs in a separate category, because nothing in the path of the call can observe it without already knowing the correct answer.

Most published success rates collapse these layers into one percentage. That is convenient for a status page and misleading for a buyer, because the layers fail independently.

Where the layers disagree

The useful cases are the ones where one layer says yes and another says no. Each of them happens in normal operation, not only during incidents.

• A 200 with an error object in the body. Transport succeeded, the response is not usable, and a monitor that only reads status codes counts it as a success.
• A handler that fails before payment settles. Transport failed and no charge occurred. The buyer lost time but not money.
• A payment that settles while the response times out or is lost on the way back. The provider may log a success. The buyer paid and received nothing.
• A response that arrives but whose settlement state is still unresolved. The content is usable, but the buyer cannot yet say what it was charged.
• A schema-valid response with the wrong answer. All three layers pass. Only quality fails, and no rate that describes the call will show it.

The third case is the expensive one. Money moved and nothing usable came back. A success rate that cannot distinguish it from a clean call is hiding the outcome a buyer most needs to avoid.

Who can see which layer

The reason the numbers drift apart is that no single party observes every layer.

You, as the provider, see your own edge: the request arrived and your handler returned. You do not see a client-side timeout, a connection dropped after your response left, or a body your buyer could not parse. Your uptime figure is a transport measure taken from the inside.

The payment facilitator and the settlement rail see whether a payment cleared. They do not see whether the work was delivered.

The buyer sees what actually arrived and what it was charged. It cannot see why something failed upstream.

A gateway or proxy sitting in the path sees the request, the response it received, the time between them and the payment state for every call routed through it. It sees more layers than anyone else, but only for its own traffic, and it still does not know whether an answer was correct.

This is the same vantage-point problem that separates measured latency from advertised latency. A number recorded at one point in the path cannot be compared with a number recorded somewhere else as if they described the same thing.

Which success a comparison can honestly claim

A comparison layer can claim only the layers it observes, and only for calls it observed. Anything beyond that is borrowed from the provider and should be labelled as such.

For a buyer reading a success-rate column, three questions decide whether the column means anything:

• Which layer was counted: status codes, settled payments, contract-valid responses, or some combination.
• Where it was counted from: the provider's edge, the buyer's client, or a proxy in the path.
• How much traffic it rests on, and over which window. A rate built on a handful of calls describes those calls, not the endpoint, which is why sample size in API benchmarks should travel with the number.

A comparison that cannot answer those questions for a candidate should not score that candidate on reliability at all. Leaving the dimension out and saying so is more honest than filling the gap with the provider's own figure, and far more honest than scoring it as zero.

How to label the number you publish

Providers usually lose credibility here not by publishing a bad number, but by publishing an ambiguous one. If you report a success rate for a paid endpoint, label the layer and the vantage point explicitly. The mechanics of the numerator and denominator are covered in the guide to API success rate measurement for paid endpoints. The labelling question comes first: say what event you are counting before you count it.

Two additions make the figure far more useful to an automated buyer. Report paid-but-undelivered calls as their own class rather than folding them into a general failure count. And publish what happens to the buyer's money in that case. An agent that knows the endpoint has machine-readable refund rules can reconcile a lost response instead of retrying blindly and paying twice.

What you should not do is describe a transport rate as reliability, or imply that a high success rate means correct answers. A buyer that later finds the two were different will discount everything else you publish.

Where Apiosk fits

Apiosk measures success rate and latency for listings it has proxied enough calls of, which means the figure describes what happened to calls routed through the gateway. It is not a statement about whether the answers were right. Apiosk does not measure result quality or provider terms.

In `/v1/compare`, the measured success rate sits beside price, measured latency and input compatibility, each scored 0–100 relative to the candidates in that one comparison. Every response carries the weights that produced the score and each candidate's contribution per dimension. Where a candidate has not been measured, the dimension is dropped from its weighting and named, never scored as zero. A buyer that needs a floor can pass `min_reliability` once and `/v1/decide` will remove any candidate below it, naming that constraint as the reason.

If you run a paid endpoint and want buyers to see a success rate they can trust, list it as a reviewed provider and publish an output contract precise enough that a usable response can be told apart from a merely successful one.