Skip to content
Velloreth
Programming 6 min read

Designing API Error Responses That Help

A good error response tells the client what went wrong and what to do. Learn the status codes, the body shape, and the validation errors.

By

The status code

The status code tells the client the class of the problem.

CodeMeaning
400Bad request — malformed
401Unauthenticated
403Forbidden
404Not found
409Conflict
422Validation failed
429Rate limited
500Server error
503Unavailable

A 4xx is the client’s fault, and a retry with the same request will fail again.

A 5xx is the server’s fault, and a retry may succeed.

This distinction is what a client uses to decide whether to retry, which is why it matters more than the exact code.

401 versus 403

401 Unauthenticated — the request has no valid credentials. The client should authenticate and retry.

403 Forbidden — the request is authenticated but not permitted. Authenticating again will not help.

The confusion is common. A 403 for a missing token is wrong, because the client cannot tell that it needs to log in.

A 401 must include a WWW-Authenticate header, which tells the client how to authenticate.

The body shape

{
  "error": {
    "code": "validation_failed",
    "message": "The request body is invalid.",
    "details": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "Must be a valid email address."
      }
    ],
    "request_id": "req_8f3a2b"
  }
}

code is machine-readable, and a client branches on it.

message is for a developer, and it is not for logic.

details names the specific fields.

request_id lets a support request be traced to a log line, which is the single most useful field in a production error.

Validation errors

Name every field that failed, not only the first.

{
  "error": {
    "code": "validation_failed",
    "message": "2 fields are invalid.",
    "details": [
      { "field": "email", "code": "invalid_format" },
      { "field": "age", "code": "too_small", "minimum": 18 }
    ]
  }
}

Returning only the first error forces the user to fix one field, submit, and discover the next, which is a poor experience.

Include the constraint where it helps, such as the minimum or the allowed values.

Use a stable field path for a nested object, such as address.postcode.

The problem detail standard

RFC 9457 defines a standard error body.

{
  "type": "https://example.com/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "The email field must be a valid address.",
  "instance": "/users"
}

type is a URI that identifies the error class, and it can be a documentation link.

title is a short, human-readable summary.

status repeats the HTTP status.

detail is the specific explanation.

instance identifies the request.

The advantage: it is a standard, so a client library can handle it generically.

What not to do

Return 200 with an error in the body. It breaks every client, cache, and monitoring tool.

Leak a stack trace. It exposes the internals and may reveal a path or a version.

Leak a database error. A unique constraint violation should become a 409 with a clear message, not the raw SQL error.

Use a different shape per endpoint. A client should not need a special case for each error.

Return a 500 for a validation error. It tells the client to retry, which will fail again.

Return a 404 for an authorization failure. It hides the resource’s existence, which is sometimes deliberate, and it is confusing when it is not.

Use a message as a code. A message changes; a code is a contract.

Rate limiting

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1730000000

Retry-After tells the client when to try again, in seconds or as a date.

The rate-limit headers let a client slow down before it is blocked, which is better than a hard failure.

A 429 is a 4xx, so a naive client does not retry. The Retry-After header is what makes the retry correct.

Idempotency

A retry of a POST can create a duplicate.

The fix is an idempotency key:

POST /payments
Idempotency-Key: 8f3a2b1c-...

The server stores the key and the result, and a retry with the same key returns the original result rather than creating a second payment.

This is essential for a payment or any non-idempotent operation, because a network timeout leaves the client unsure whether the request succeeded.

Testing an error response

An error path is code, and it deserves the same tests as the happy path, which is the part that is usually skipped. The tests worth writing are the status code for each failure, the body shape, the presence of a request_id, and the behaviour of a client that receives the error. A contract test that asserts the error shape catches a change that would break a client, and it is the test that is most often missing. The second practice is to test the error from the client’s side, because a client that does not check the status code will treat a 500 as a success, and the bug is in the client rather than the server. The third is to log the error with the request_id, so a support request can be traced, and to make sure the log does not contain the sensitive part of the request.

Practical guidance

  • Use the right status code.
  • Distinguish 401 from 403.
  • Return a machine-readable code.
  • Name every invalid field.
  • Include a request_id.
  • Never leak a stack trace.
  • Never return 200 with an error.
  • Add Retry-After to a 429.
  • Support an idempotency key for a non-idempotent operation.

For the related guides, see rest-api-design-principles and http-status-codes-explained. For the broader context, api-versioning-strategies and error-handling-patterns.

Quotable summary

The status code tells the client the class of the problem and the body tells it the detail, and the distinction between a 4xx and a 5xx determines whether a retry makes sense, because a 4xx is the client’s fault and a 5xx is the server’s. A validation error should name every field that failed rather than only the first, because returning one error at a time forces the user to fix a field, submit, and discover the next. A machine-readable code is more useful than a human message because a client can branch on it, and a request_id is the single most useful field in a production error because it lets a support request be traced to a log line. Never leak a stack trace or a database error, and never return 200 with an error in the body, because it breaks every client, cache, and monitoring tool that relies on the status code.

Frequently asked questions

What status code should I return for a validation error?
422 Unprocessable Entity, or 400 Bad Request. 422 is more precise: the request was well-formed but the content is invalid.
What is the difference between 401 and 403?
401 means the request is not authenticated, so the client should log in. 403 means it is authenticated but not permitted, so logging in again will not help.
Should an error response include a message?
Yes, a human-readable message for a developer, alongside a machine-readable code. Do not rely on the message for logic.
What is a problem detail?
A standard error body defined by RFC 9457, with fields such as type, title, status, detail and instance.
Should I return 200 with an error in the body?
No. It breaks every client, cache and monitoring tool that relies on the status code.
How do I handle a partial failure?
Return 207 Multi-Status with a per-item result, or fail the whole request. A partial success with a 200 is ambiguous.