RFC 7807
lastmod 2025-06-09created 2025-06-092 edits
Problem Details for HTTP APIs (clear error messages)
Overview and purpose
In a REST API, when an error occurs on a client request, the server sends an HTTP status error code. (400 bad request, 404 not found)
However, it is hard to pinpoint the cause of an error from the HTTP status code alone. What is used then is sending an error message containing information about the error in the Response Body.
Now the problem is that you have to think about what to put in the error message. The RFC 7807 standard is what saves you this trouble.
This time, let's look at the structure and contents of the error message proposed by RFC7807.
Caveats when using error messages
- First focus on providing an appropriate HTTP status code for the error situation.
- Don't return just a bare error code; include human-readable information.
- Be careful about security in production service environments.
In a typical service architecture in production, it is advisable not to include error stack information in API error messages.
If, depending on options, the service returns error stack information in REST API error response messages when started in dev mode or similar, it can be very useful for debugging.
Error message structure proposed by RFC7807
It consists of 5 fields in total.
- type : URI identifier for classifying the error
- title : Brief description of the error
- status(optional) : HTTP response code
- detail : Detailed description of the error
- instance : URI where the error originated
Examples
Example) Error message sent when a duplicate login id is used during member sign-up
{
"type": "/errors/member/join/duplicate-login-name",
"title": "DuplicatedLoginName",
"status": 409,
"detail": "Company member join fail due to DuplicatedLoginName",
"instance": "/api/delivery-service/company/member/join"
}
Example) Error message sent for a Request containing blanks during member sign-up
{
"type": "/errors/member/join/blank-input",
"title": "BlackException",
"status": 400,
"detail": "Company member join fail due to blank input request",
"instance": "/api/delivery-service/company/member/join"
}