An API designed for builders (and the AIs that help them)

Integrations fail in boring ways: wrong path, missing header, expired token. The failure mode for most APIs is a short status line and silence. For a human, that means tab-switching and guesswork. For an autonomous client or coding assistant, it often means stop—no recovery hook, no machine-readable next step.

HUMΛN treats that silence as a product defect. Exquisite failures are part of the Canon: the platform should orient you toward the next action, not just deny the current one.

This post walks three surfaces that make the API self-describing:

GET /v1/discover — public “first contact” with authentication guidance, OpenAPI pointer, and common entry routes.
Enriched 401 responses — RFC 7807 ProblemDetails with a discovery block (where to authenticate, where the spec lives).
Global 404 handler — suggestions for nearby routes so typos don’t become archaeology.

Together, they reduce the time from “something broke” to “I know exactly what to do.”

Why first contact matters

Agents and developers share the same onboarding problem: they need a stable map before they can navigate. OpenAPI is that map—but you have to know it exists and where to fetch it.

GET /v1/discover answers “what is this API?” without credentials. It points to /v1/openapi.json, documents bearer-style authentication formats at a high level, and links human-oriented guides where policy requires the long form.

For autonomous tooling, discovery is composable: fetch discover → follow api_reference → generate or validate calls against the spec.

When authentication fails, teach—not just reject

A naked 401 says “no.” A teaching 401 says “no, and here is the keyring.”

Extended ProblemDetails for authentication failures include discovery, for example:

platform_info — try GET /v1/discover (no auth).
api_reference — GET /v1/openapi.json.
authenticate — session or delegation path reminders.
guide — human-readable auth documentation.

Coding assistants can parse this block and propose the fix: obtain a delegation token, refresh a session, or open the guide—all without inventing URLs.

404 as a routing hint engine

Typos in paths are universal: pluralization, swapped segments, missing version prefix.

The global not-found handler returns RFC ProblemDetails plus suggestions: a small set of method + path pairs that plausibly match what the caller meant, plus discovery pointers back to OpenAPI and /v1/discover.

It does not pretend to read minds—it narrows search space honestly. That is often enough for humans; for machines, it is structured input to a repair loop (“retry with suggested path”).

Practice: a minimal client recovery loop

On 401, read discovery.authenticate and discovery.guide; never guess vendor-specific OAuth dance from scratch.
On 404, inspect suggestions before broad search.
On cold start, GET /v1/discover once per environment and cache the result with your OpenAPI snapshot version.

Closing

Self-describing APIs are not vanity—they are throughput. They keep humans sovereign (clear escalation to real auth flows) and keep automation honest (verifiable next steps). If the only thing your error returns is a status code, you have shifted the burden to every integrator, forever.

Ship errors that teach. Ship discovery that needs no secret handshake. The boring integrations become reliable—and the clever ones become possible.