Designing API Error Responses Humans Can Parse

Error shapes integrators can use.

The Problem

Partner integrations broke on validation errors that returned generic 400 bodies — "Something went wrong" and a stack trace in logs nobody else could see.

Shape I Standardized On

{
  "error": {
    "code": "order.missing_line_items",
    "message": "At least one line item is required.",
    "field": "line_items",
    "docs": "https://example.com/docs/errors#order.missing_line_items"
  }
}

Rules

• code — stable string integrators can branch on; never rename without versioning
• message — human-readable, safe to show in UIs
• field — optional; maps validation to form inputs
• HTTP status — 422 for validation, 409 for conflicts, 429 with Retry-After when rate limited

Why It Matters

Good errors are product features for API consumers. They reduce support load and make your platform feel intentional.