Your API Isn't Ready for Agent Customers. Here's What Breaks First.

Last month I pointed an autonomous agent at four paid APIs: Contentful's CMA for publishing, fal.ai for image generation, Agenthansa for bounty discovery and a Solana RPC endpoint for on-chain payments. I expected integration work. That's the job. What I did not expect was that the friction would have almost nothing to do with my code, and almost everything to do with a single variable: how much each API still assumed a human was sitting in front of it.

None of the four threw a CAPTCHA at me. None forced a browser redirect. All four were reachable by a program holding a key. The interesting part is what happened after the connection opened, the small machine-hostile gaps that a human clicking through a UI never notices and an agent face-plants on. fal.ai's 500'd my Python before it sent a single byte over the wire. Contentful made me run a five-call handshake just to attach one image. An image model accepted my instructions and quietly ignored half of them.

This is a field report from the consumer side, not the API-vendor side. Real APIs, named, with the exact friction I hit and what each would need to change to be genuinely agent-ready. No theory, no "10 best practices" listicle. And the pattern underneath all of it is the same: the closer an API was designed to a human workflow, the harder it fought my agent.

---

Authentication: The Conventions an Agent Can't Guess

The agent's first job is to authenticate, and here is the thing nobody writes down: an agent reaches for the convention before it reaches for the docs. For token APIs that convention is Authorization: Bearer <token>. It is so close to universal that it is effectively the default baked into every HTTP client and every code-generation path an agent might take.

fal.ai breaks that assumption with one word. Its header is Authorization: Key <token>, not Bearer. One word. A human skims the quickstart, copies the snippet and never thinks about it again. An agent discovering the API cold defaults to Bearer, gets a flat 401, and the 401 contains nothing that says "wrong auth scheme, try Key." I only got it right because I had read fal's docs by hand. The deviation is real, it lives in prose and it is invisible to a machine until the machine has already failed.

The three that worked got auth right by being ordinary. Contentful's CMA uses standard Authorization: Bearer, token-based, no browser step, no redirect and it authenticated on the first call. Agenthansa is agent-native, built from day one assuming the caller is software. Solana RPC needs no API auth at all: you sign the transaction with a keypair and the network verifies the signature, machine-native by construction.

So the auth gap here is not OAuth or MFA, the failures everyone warns about. It is subtler and far more common: tiny deviations from the conventions agents assume, documented only in human prose. Key instead of Bearer is harmless to a person and a dead end to a bot, because the bot has no spec to check and the error gives it nothing to correct against.

What agent-ready auth actually looks like:

• Token-based flows with no browser redirect at any step (which all four got right)
• The auth scheme expressed in a machine-readable spec, not only a prose quickstart, so an agent discovers Key vs Bearer before it fails
• Auth errors that name the failure ("unsupported authorization scheme") instead of a bare 401
• Rate limiting that distinguishes autonomous high-throughput usage from abuse, because agents do not take coffee breaks

The Errors Were Fine. The Silence Wasn't.

Conventional wisdom says the agent-killer is bad error handling: HTML 500s, vague messages, missing Retry-After. That is real, and I will get to the bar it sets. But across these four APIs the errors were mostly fine. fal.ai returns clean JSON on every status code, error code plus message, and the agent parses it and adjusts. Contentful's CMA returns a structured 409 the moment your X-Contentful-Version header does not match the entry's current version, which happens constantly because every write bumps the version, and the 409 tells the agent exactly what went wrong so it can refetch and retry. When the machine can read the failure, the machine recovers.

The two things that actually burned me were not errors at all.

First, silent non-compliance. nano-banana, fal's image model, takes a prompt that includes "16:9 wide landscape banner format." It accepts it. Returns HTTP 200. And hands back an image that is roughly square. No error, no warning, no field saying "aspect ratio unsupported, ignored." For a human that is a shrug and a crop. For an agent it is poison: there is no failure to branch on. The call succeeded, the output is wrong and the only way to know is to decode the image and measure it. A 200 that does not honor the request is worse than an honest 400, because the agent has nothing to catch.

Second, the client environment. My very first fal.ai call never reached fal.ai. Homebrew Python on macOS threw SSL: CERTIFICATE_VERIFY_FAILED against fal.run before a single byte left the machine. The fix was to stop using Python's urllib and shell out to curl, which uses the macOS system trust store. That is not fal's bug in the strict sense. But it is the agent-readiness lesson hiding in plain sight: APIs assume a "normal" HTTP client, and an agent's real runtime, whatever Python a coding agent happens to be driving, often is not one. An API that wants agent traffic cannot assume the caller's TLS stack is sane.

What agent-ready errors look like:

• Structured JSON on every status code, including 5xx, never HTML or plain text
• Machine-readable error codes alongside human messages, so the agent can branch on error_code: "rate_limited" without parsing English prose
• Retry-After on every 429 and 503, as the HTTP spec already requires and most APIs ignore
• Explicit signals when an input is accepted but ignored, instead of a 200 that quietly drops half the request
• A consistent error schema documented in the spec, so the agent knows the shape of failure before it happens

Stripe got this right years ago: structured, typed, documented in the spec. Every API expecting autonomous callers needs to match that bar, and then go one step further by refusing to fail silently.

The Documentation Is a Website (and the Agent Can't Read It)

Every piece of friction so far shared one trait: it lived in prose. Key not Bearer, buried in a quickstart. nano-banana's aspect-ratio behavior, learnable only by generating an image and measuring it. None of it sat in a machine-readable spec the agent could check before acting.

The sharpest version of this was Contentful's asset workflow. Attaching one hero image to one post is not a single call. It is five, in strict order: upload the raw bytes to a different host (upload.contentful.com, not the API host), create an asset entry that references the upload, PUT to a process endpoint with an X-Contentful-Version header, poll the asset until the file URL actually populates, then publish the asset, because an unpublished asset cannot be linked from an entry you intend to publish. Miss the version header and you get a 409. Skip the publish and the link silently resolves to nothing.

A human never sees any of this. In the Contentful web app you drag an image into a field and the UI runs the whole dance for you. That five-call sequence is the UI's internal choreography, and it exists in the docs as prose and example code, not as one spec'd "attach media" operation an agent can discover and execute. Contentful even publishes an OpenAPI spec, which is more than most APIs manage, and the spec still does not capture the workflow, only the individual endpoints. The agent has to reconstruct the order of operations from documentation written for a person.

That is the real shape of the docs-as-website problem. It is not always "there is no spec." Sometimes the endpoints are perfectly spec'd and the process that strings them together, the part a human absorbs by clicking around, is the thing that only exists in prose.

The Model Context Protocol partially solves this at the tool-discovery layer. MCP servers expose their capabilities in a format agents consume directly. But the underlying API still needs machine-readable specs for the MCP server to wrap it correctly. If your API ships no spec, or specs the endpoints but not the workflow, your MCP wrapper is built on hand-translated documentation, which means it drifts out of sync the moment someone ships a change.

What agent-ready documentation looks like:

• A published, versioned OpenAPI 3.1 spec at a stable, public URL
• Multi-step workflows expressed as spec'd operations or state machines, not left implicit in tutorial prose
• Changelog entries as structured data, not blog posts
• Deprecated endpoints flagged in the spec with sunset dates

The APIs That Just Worked Were Built for Machines

It is worth stating plainly which of the four gave my agent the least trouble: Solana RPC and Agenthansa. Neither was designed for a human in a browser. Solana RPC is keyless JSON-RPC. You construct a request, sign it with a keypair, the network verifies, and there is no consent screen, no dashboard, no developer-experience layer wrapped around a human workflow, because the caller was always assumed to be a program. Agenthansa is agent-native by design, built for software consumers from day one.

They were not easier because they were simpler. Solana's transaction model is arguably harder than posting JSON to Contentful. They were easier because nothing in the path assumed eyes, a browser, or a human's patience for prose. The friction in this whole experiment tracked exactly one variable, and it was not complexity. It was how much human the API still had baked in.

That is the thesis in one line: agent-readiness is not a feature you add. It is a set of assumptions you remove.

The Business Case for Agent-Readiness

This is not a theoretical problem for next year. The opportunity I mapped in my agent commerce post is already live: roughly $600 million in agent payment volume, over 69,000 active agents and 11,000+ MCP servers. Every one of those agents is calling APIs right now.

The question for API providers is no longer "should we support agents?" It is "how much agent traffic are we already losing because our API rejects them silently, or worse, accepts them and returns the wrong thing?"

Here is the competitive framing. If two APIs offer the same service and one is agent-ready (predictable auth, structured errors, no silent non-compliance, a published OpenAPI spec) while the other assumes a human in the loop, the agent-ready API wins every agent customer by default. This is not a feature comparison. It is a binary gate. Your API either works for an autonomous caller or it does not.

The MCP multiplier makes this sharper. An API with a clean spec can be wrapped as an MCP server in hours. An API whose real workflow only exists in tutorial prose cannot be wrapped reliably at all without a human building and babysitting a custom adapter. The MCP ecosystem is becoming the distribution channel for agent commerce, and agent-readiness is the entry ticket.

The Agent-Readiness Checklist

Run this on your own API. If more than two answers are "no," your API is not ready for agent customers.

Authentication

• Does the API support token-based auth with no browser redirect at any step?
• Is the auth scheme discoverable in a spec, not only in a prose quickstart?
• Do auth errors name the failure instead of returning a bare 401?

Error Handling

• Does every status code return structured JSON, including 5xx errors?
• Are there machine-readable error codes alongside human messages?
• Is Retry-After present on every 429 and 503 response?
• Does the API signal when an input is accepted but ignored, rather than returning a 200 that quietly drops it?

Documentation

• Is there a published OpenAPI 3.1 spec at a stable URL?
• Are multi-step workflows spec'd, or do they only exist as tutorial prose?
• Are deprecated endpoints flagged with sunset dates?

Rate Limits

• Are limits documented in the spec, not just in a FAQ?
• Are they high enough for autonomous usage?
• Is there a programmatic way to request higher limits?

Idempotency

• Do write endpoints accept idempotency keys? Agents retry aggressively. Without idempotency, retries cause duplicate charges, duplicate records and data corruption. Stripe's idempotency key pattern is the gold standard here.

Webhooks and Callbacks

• Does the API support push notifications for async operations, or does it force polling? Agents poll expensively. Webhooks are cheaper and faster for both sides.

What I'd Build Differently

The mental shift is simple. Design the API for a customer that has no eyes, no browser, no patience for ambiguity and will call you 10,000 times in an hour. Then make it pleasant for humans as a secondary concern. This is the inverse of how almost every API is designed today.

The pattern I would propose to any client building an API that expects agent traffic:

• OpenAPI spec as the source of truth, generated from code, with multi-step workflows expressed explicitly instead of left to tutorials
• Structured errors on every endpoint, with machine-readable codes, field-level detail and an explicit signal whenever an input is accepted but not honored
• Predictable, conventional auth, standard Bearer tokens with no surprises, designed as a first-class pattern rather than a developer shortcut
• Idempotency keys on every write endpoint, because autonomous callers retry without asking
• Webhooks for every async operation, because polling at agent scale is wasteful for everyone
• A /health endpoint that returns machine-readable status, not just "OK" rendered in HTML

The same containment thinking that led me to configure agent guardrails in AGENTS.md applies here. You define the boundaries explicitly, in a format the machine can enforce, rather than hoping the caller reads the documentation and behaves politely.

And the MCP-ready layer sits on top of all of this. Publish an MCP server wrapper alongside the API itself. The MCP server becomes the agent-facing interface. The API becomes the engine. This is the architecture I would propose to any client building for the agent commerce layer.

Conclusion

The agent-readiness gap is not a bug in your API. It is a mismatch between who you designed for and who is actually calling. None of the four APIs I tested were broken. Three of them were close to agent-ready and tripped my agent on a single word, a silent 200 or a five-call workflow buried in prose. The APIs that gave me no trouble were the ones that never assumed a human in the first place.

The providers that close this gap first will own the agent distribution channel. The ones that do not will wonder why their traffic is flat while their competitor's MCP server is doing 10,000 calls a day.

If you are building APIs or MCP servers and want to work through these agent-readiness patterns with other senior devs doing the same, that is exactly what The Agentic Architect Lab is for. We are shipping real agent infrastructure, not talking about it.

And if you run an API product and want a proper agent-readiness audit beyond the checklist above, that is work I take on. The checklist gets you started. The full audit finds the silent failures the checklist cannot see.

Sources

• OpenAPI Specification 3.1
• Model Context Protocol documentation
• x402 protocol documentation (Coinbase)
• Contentful Content Management API reference
• fal.ai API documentation
• Agenthansa
• Solana RPC documentation
• HTTP 429 Retry-After (MDN)
• Idempotency keys (Stripe)