API Design3 minOct 2024

The Art of Meaningful Error Messages

Most API errors I see are useless. I've developed a convention for error responses that includes machine-readable codes, human-readable messages, and enough context for a developer to fix the issue without opening the logs.

I've seen too many APIs return { "error": "Something went wrong" } and call it a day. That's not an error response — it's a shrug in JSON format.

After building and consuming dozens of APIs, I've settled on a convention that balances machine readability with developer empathy.

The Response Format

Every error response follows this structure:

Example

A validation error on a seat reservation:

{
  "code": "SEAT_UNAVAILABLE",
  "message": "The requested seat is no longer available",
  "detail": "Seat A12 at event 'Tech Summit 2024' was booked 0.3s before your request",
  "requestId": "req_8f3a2b"
}

Why This Matters

•Frontend developers — can display the message directly to users and use the code for conditional UI logic

•API consumers — have enough context to debug without contacting you

•Your logging system — gets structured data for alerting and analysis

I've used this pattern across six production APIs and it consistently reduces integration support tickets by roughly 60%.