Describe your API design: versioning, error contracts, idempotency, rate limiting. Convince me it was designed, not accreted.?

The full executive answer

It was designed, and every element I describe is in the code today. Versioning: the public API lives under a versioned path — /api/v1 — with the version also stamped inside every webhook envelope, so breaking changes mean a new version, never a silent mutation. The whole surface is described by an OpenAPI 3.1 specification served from the API itself — OpenAPI being the industry standard machine-readable contract, so your team can generate clients and validate against it mechanically.

Contracts: every endpoint returns one standard envelope — success wraps the payload with an explicit ok flag, errors return a structured object with a message, a stable machine-readable error code, and details. One shape, 414 endpoints, no surprises. Idempotency: mutating endpoints accept an Idempotency-Key header — your client sends a unique key with a write, and if the network drops and you retry, we replay the original response instead of double-creating work. It is engineered properly: the request is fingerprinted, a database uniqueness constraint makes the claim race-safe under concurrency, and a retry that reuses a key with a different body is rejected with a conflict — the same semantics Stripe pioneered.

Rate limiting: per-key limits per minute and per day, with tier-level defaults stored in the database and per-key overrides for negotiated contracts — so one runaway integration cannot degrade the platform for anyone else, which is a fairness and availability control, not just abuse defence. All API-key requests are logged and audit-evented. This is the checklist an architect runs — and I would genuinely invite your team to diff our OpenAPI document against your API standards.