Errors and Idempotency

Error bodies clients can use

Include a stable machine code plus a human message. Avoid leaking stack traces to public clients.

{
  "error": "rate_limited",
  "message": "Too many requests. Try again in 30s."
}

Map to status codes

Validation → 400/422, auth → 401/403, missing → 404, conflict → 409, upstream failure → 502/503.

Idempotency keys

For payments or creates, clients send a unique key so retries do not double-charge or double-create.

POST /api/orders
Idempotency-Key: 7f3c2a...
Content-Type: application/json

Retries

Clients may retry on network failures. Design POST endpoints knowing that duplicates can happen without idempotency support.