Skip to content
BENIBIX Learn

API Error Response

Development🔌 APIsAPI Design Practices

Also known as Error Response, Problem Details, application/problem+json, RFC 9457

What an API sends back when a request fails. It gives a code and a reason.

Think of it like

Think of it like a note on a locked door. It says why you cannot get in and what to do next.

Example

Jack asks for order 42, which does not exist. The API answers 404 with the title Order not found.

Why it matters

Good errors tell the caller how to fix the problem, which saves hours of guessing.

Definition

An error response is what an API sends back when a request fails. It has an HTTP status code, like 404 or 500. It should also have a body that explains what went wrong. A web standard called Problem Details gives that body a set shape. Its fields include type, title, status and detail.

Example code

json
{
  "type": "https://example.com/errors/not-found",
  "title": "Order not found",
  "status": 404,
  "detail": "No order has the number 42.",
  "instance": "/orders/42"
}
A Problem Details body: the code for programs, the words for people.
Status 404 with a body that says what went wrong.

Common mistake

Sending status 200 with an error inside. Programs read the status code first and think it worked.

Key takeaways

  1. 1
    Right status code. 404, 400, 500 and so on.
  2. 2
    Say why. A body that explains it.
  3. 3
    Same shape. Every error looks alike.