The honest API contract

---
name: honest-api
description: "Applies “The honest API contract” as a repeatable product-quality gate. Use during backend work when typed boundaries, one error envelope, no lying 200s."
---

# The honest API contract

Apply this skill during **Backend** work. It supports Node / API, Python, Any stack.

Typed boundaries, one error envelope, no lying 200s.

## Instructions

Every API boundary validates input against a schema and rejects loudly — never trust the client. Responses use one consistent envelope; errors carry a machine code, a human-readable message, and a correlation id. Status codes must be honest: no 200-with-error-body, no silent catch-and-continue. Make mutations idempotent (idempotency keys or natural idempotence) and state the timeout/retry policy for every outbound call. If a failure path isn't handled, fail fast and visibly rather than guessing.

## Detect the problem

- 200 with { error } inside
- A different error shape per endpoint
- Retry logic 'to be added later'

## Hold the gate

Do not declare this phase complete until every item passes:

- [ ] Every endpoint has a typed request/response schema validated at the boundary
- [ ] One error envelope everywhere: code, human message, correlation id
- [ ] Status codes tell the truth — no 200 with { error } inside
- [ ] Mutations are idempotent or explicitly guarded against replay
- [ ] Timeouts, retries, and rate limits exist and are written down

## Verify the result

Send malformed input to every endpoint — every response uses the one envelope and an honest status code.