BlogAPI design

Every error wears the same four fields

API errors share code, message, docs, and request_id, so the same handler can explain failures across endpoints.

Successful responses need different fields because each endpoint answers a different question. Errors don't need that much variety. If every endpoint invented its own format, you'd have to learn another response shape each time you added a lookup.

A postal code we can't find returns 404:

{
  "code": "not_found",
  "message": "Postal code not found: 00000 (US)",
  "docs": "https://parseapi.com/docs#not_found",
  "request_id": "req_msl1m5nz_0ty9wq1"
}

A request without an API key returns 401:

{
  "code": "invalid_api_key",
  "message": "Invalid or missing API key",
  "docs": "https://parseapi.com/docs#invalid_api_key",
  "request_id": "req_msl1m60q_y9gp7uw"
}

The status and values change, but the four fields keep the same jobs. Your code branches on code. A person reads message. The docs link explains the error, and request_id identifies the request when you're investigating it.

That lets you write one error handler for the API. It still needs to respond differently to a missing key and a missing record, but it can read, display, and log both errors the same way. You shouldn't have to debug the error format while you're trying to debug the request.