A customer got charged twice. Same card. Same $400. Eleven minutes apart.
The founder called me in a panic. Not because the money was huge. Because the customer was their biggest account, and the second charge landed while that customer was sitting in a renewal meeting.
Here is what actually happened. Their checkout had a slow network moment. The customer clicked pay, nothing happened for a few seconds, so they clicked again. Two requests went out. The payment provider treated them as two separate charges. Two receipts. One angry phone call.
The fix was not more code. The fix was a payment API that knew the difference between "try again" and "do it again."
That is the whole story of good API design, told in one bad afternoon. And it is a story most non-technical leaders never get to hear, because by the time the consequences reach them, they look like customer service problems or churn numbers, not design decisions made months earlier in a room they were not in.
This piece is my attempt to put you in that room.
Why a non-technical leader should care about APIs at all
Let me define the term in the most boring way possible, because boring is the point.
An API is the way two pieces of software talk to each other. When your billing system tells your email tool to send a receipt, that is an API call. When a partner's app pulls data out of yours, that is an API. When your mobile app asks your server for a customer's order history, API again.
You will never write one. That is fine. Neither will most of your buyers.
But here is what I have learned in years of building software for clients: the API is one of the most honest signals a company sends about how it operates. It is the part of your product that other professionals touch directly, usually before they have signed anything. It is a handshake, and like a handshake, people decide a lot about you in the first three seconds.
I have written before about how most B2B websites are brochures that talk at buyers instead of helping them do anything. An API is the opposite surface. Nobody markets it. Nobody polishes it for a pitch. It is just sitting there, doing exactly what it does, telling the truth about your engineering culture to anyone who looks.
So when I say "you should care about API design," I am not asking you to learn to code. I am asking you to learn to read one signal that your customers and partners are already reading without you.
The fastest way to learn to read it is to study three companies that get it right. Let us go.
Stripe: reliability is a product decision
Stripe processes payments for millions of businesses. They could compete on price, on speed, on the size of their logo wall. Instead, a big part of why developers trust Stripe is something most buyers never see: they made retries safe.
Back to the double charge. The reason that customer got billed twice is that the payment provider had no memory. Each request arrived fresh, with no way to know it was a duplicate. Click twice, pay twice.
Stripe solved this with what engineers call an idempotency key. Skip the jargon and keep the idea. When your app sends Stripe a payment, it attaches a unique tag to that specific attempt. If a request with the same tag shows up again, Stripe recognizes it, says "I already handled this one," and returns the original result instead of creating a second charge.
In plain English: clicking pay twice does not pay twice.
Read that as a business statement, not a technical one. Stripe decided, as a matter of product strategy, that a customer should never be punished for a slow connection or a nervous double-click. That decision cost engineering time. It bought something more valuable: trust at the exact moment money changes hands.
The provider my client had chosen made the opposite decision, probably without ever framing it as a decision. Same checkout flow on the surface. Completely different outcome when the network hiccupped. One company treated reliability as part of the product. The other treated it as the customer's problem.
You can feel which one you would rather buy from. Your customers can too.
The lesson for leaders: reliability is not a backend detail you delegate and forget. It is a promise your product makes or breaks, and you are allowed to ask whether your tools are making it.
GitHub: clarity is a sales tool
GitHub's API is a masterclass in being guessable.
It is built around nouns you already understand. Repositories. Issues. Pull requests. The web addresses read like plain language: /repos, /issues, /pulls. The actions are standard and boring. You use "get" to read something, "post" to create something, "delete" to remove it. There is no secret handshake. If you know what you want, you can usually guess how to ask for it.
Compare that to an API I once had to integrate for a client. The main endpoint was called /processData. Not "orders." Not "invoices." processData. To find out what it actually did, you had to read a forty-page document, and the document was wrong in two places.
Here is why this matters to someone who will never read either API. The first hour a partner spends integrating with you sets their expectation for the entire relationship. If your API reads like plain language, their engineer relaxes. The integration feels safe, which makes your whole company feel safe. If your API reads like /processData2_final, that engineer quietly starts wondering what else inside your company is held together with tape.
And then they tell their boss.
I have watched integration deals stall for exactly this reason. Not price. Not features. A partner's engineer spent a confusing day, came away uneasy, and recommended caution. The deal died in a place no salesperson can see and no marketing campaign can reach. The product was fine. The handshake was not.
This connects to something I believe about how buyers actually evaluate technical partners. When I wrote about how to evaluate agentic AI vendors like tech partners, the core idea was the same: the surface a vendor exposes to you, before any contract, tells you how they will behave after the contract. An API is that surface, made of code.
The lesson for leaders: clarity is not a nicety. Clarity is friction removed from every future deal, and friction is where revenue quietly leaks out.
Twilio: errors are part of your customer experience
Twilio is famous among developers for something almost comically unglamorous: good error messages.
When something goes wrong with a Twilio request, you do not get a shrug. You get a specific error code, a plain-language description of what happened, and a link to the documentation that explains how to fix it. The failure arrives with instructions attached.
Now picture the alternative, which is what most systems actually do. Something breaks and you get a "500 Internal Server Error" and nothing else. No code you can look up. No reason. No next step. Just a wall.
So your team starts guessing. They refresh dashboards. They re-read code that worked yesterday. They post "is anyone else seeing this?" in Slack at 11pm. The outage is bad. The silence around the outage is what turns one bad hour into three.
Here is the reframe I want every leader to internalize. Errors are not rare edge cases that only engineers deal with. Errors are part of your product's experience, because every customer and every partner eventually hits one. The only real question is whether your system helps them recover or leaves them stranded.
A clear error turns a failure into a quick fix. The integration breaks, someone reads the message, they correct the input, they move on. A vague error turns the identical failure into churn. The integration breaks, nobody knows why, frustration builds, and somewhere in that fog a customer decides you are not worth the trouble.
Same failure. Two completely different business outcomes. The difference is entirely a design choice about how you communicate when things go wrong.
The lesson for leaders: how your product fails is part of how your product sells. Design the failure, not just the success.
The pattern, in business terms
Three companies. Three lessons. One underlying idea.
Reliability is a product decision. Stripe decided retries should be safe, so customers trust the checkout at the most fragile moment. That trust is worth more than the engineering it took to build.
Clarity is a sales tool. GitHub decided integrating should feel obvious, so partners relax in the first hour. Obvious lowers the friction on every partnership you will ever sign.
Errors are part of your UX. Twilio decided that failing should come with a map, so a broken moment becomes a quick recovery instead of a quiet exit. A good failure protects the relationship.
Notice what is missing from all three lessons: you do not need to read a single line of code to understand any of them. You need to ask better questions about the products your company builds and the tools it depends on.
That is a leadership skill, not a technical one.
The four questions I ask before trusting any third-party API
When my team is about to build something important on top of someone else's API, the kind of dependency that would hurt to unwind later, we sit down and walk through four questions. None of them are clever. All of them are uncomfortable in the right way.
1. What happens when we send the same request twice? This is the Stripe question. If the honest answer is "it does the thing twice," we have just discovered a double-charge waiting to happen. We either find a provider that handles this or we build our own protection around theirs. We do not pretend the network will always behave.
2. Could a smart person guess how this works without the docs? This is the GitHub question. If the answer is no, every engineer who ever touches this integration, including our future selves, pays a tax. Sometimes the value is worth the tax. But we name the tax out loud before we sign up for it.
3. When this fails, will we know why? This is the Twilio question. We deliberately trigger a few failures during evaluation and read what comes back. If the errors are vague, we know our future 2am incidents will be longer and our customers' bad moments will be worse.
4. Who is responsible when this breaks at the worst possible time? This is the question that has nothing to do with code and everything to do with running a business. An API is a relationship. We want to know whether the company behind it answers the phone.
If we cannot get good answers to these four, we do not necessarily walk away. But we go in with our eyes open, and we price the risk into the decision instead of discovering it during a renewal meeting.
What you can actually do this week
You do not need to audit your whole system. You need one hour and a one-page comparison.
Ask your team, or your fractional technical leader if you have one, to put four things side by side. One Stripe documentation page. One GitHub endpoint. One Twilio error example. One of your own most important endpoints, the one a partner or your own app hits most often.
Then ask three plain-English questions about each:
- What is easy to understand here?
- What does this company promise me without my having to ask for it?
- Where does this make the reader work harder than they should?
That is the entire exercise. No re-architecture. No quarter-long project. Just an hour of looking at your own product the way a partner looks at it on day one, with three of the best examples in software sitting right next to it for contrast.
Most teams who run this walk away with two or three concrete improvements they can ship without rebuilding anything. A clearer error message. A safer retry on a critical operation. A resource name that stops making people guess. Small fixes, real business impact, no heroics required. It is the same energy I wrote about in the case for doing the boring stuff: the unglamorous work is usually where the real wins are hiding.
Why this matters more now
More and more companies are selling a platform story. Build on us. Integrate with us. Grow alongside us. It is a powerful pitch.
The catch is that in a platform story, the API is the product. It is the part the buyer's team actually touches, tests, and judges. You can have the strongest pitch deck in your category and still lose the deal in the first hour of a developer poking at your endpoints and not liking what they feel.
The leaders who win those conversations are not the most technical people in the room. They are the ones who can look at Stripe, GitHub, and Twilio, point at what makes each one trustworthy, and then say honestly, "here is the one place we are not there yet, and here is what we are doing about it."
You can be that leader. Not by learning to code, but by learning to see the pattern that good companies have already drawn for you.
You just had to see it once. Now you have.
Want a second set of eyes on your own API?
At Chykalophia, we build and audit the software layer that your customers and partners actually touch. If reading this gave you a slightly uneasy feeling about one of your own endpoints, that feeling is usually right. We run the one-page comparison above as a paid teardown, with concrete, shippable fixes ranked by business impact, not by how interesting they are to engineers.
If that would be useful, start a conversation with us. Bring the endpoint that has been nagging at you. We will tell you what a partner sees in the first hour, and what to do about it.