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 Velloreth
The status code
The status code tells the client the class of the problem.
| Code | Meaning |
|---|---|
| 400 | Bad request — malformed |
| 401 | Unauthenticated |
| 403 | Forbidden |
| 404 | Not found |
| 409 | Conflict |
| 422 | Validation failed |
| 429 | Rate limited |
| 500 | Server error |
| 503 | Unavailable |
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-Afterto 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.