API Error Response Writing — RFC 7807 & Error Design
Practice writing API error response schemas using RFC 7807 Problem Details, error code design, and human-readable vs. machine-readable error patterns.
0 / 22 completed
1 / 22
What is RFC 7807 'Problem Details' and why is it used in API error responses?
RFC 7807 defines a standard 'application/problem+json' content type with fields: type (URI identifying the error class), title (human-readable summary), status (HTTP status code), detail (human-readable explanation of this specific occurrence), instance (URI identifying this specific error occurrence). Using it means consumers can handle errors uniformly instead of parsing custom error formats per API.
2 / 22
What is the difference between the 'title' and 'detail' fields in an RFC 7807 error response?
Title: 'Insufficient account balance' — same for every instance of this error type. Detail: 'Your balance is $4.50 but the transaction requires $12.00' — specific to this occurrence. Clients can use title for error categorisation and detail for displaying context-specific messages to users. The type URI is the true machine-readable identifier; title is its human-readable companion.
3 / 22
What is the recommended design pattern for API error codes to support both human and machine consumers?
Best practice: combine a stable machine-readable code (ACCOUNT_LOCKED, VALIDATION_FAILED) with a human-readable message. Machines key on the code — never on message text, which may change. Example: { 'code': 'RATE_LIMIT_EXCEEDED', 'message': 'You have exceeded 100 requests per minute. Retry after 2024-03-15T14:31:00Z.', 'retryAfter': '2024-03-15T14:31:00Z' }. Separating the code from the message lets you localise messages without breaking client logic.
4 / 22
What is the 'instance' field in RFC 7807 used for?
instance: a URI (often a URN) pointing to the specific error occurrence. Example: 'instance': '/errors/logs/550e8400-e29b-41d4-a716-446655440000' or 'instance': 'urn:uuid:550e8400-e29b-41d4-a716-446655440000'. This lets a user copy their instance URI when contacting support, and support staff can look up the exact error context. It is optional but highly recommended for debuggability.
5 / 22
When documenting API error responses in OpenAPI, what is the recommended practice for the 'type' URI in RFC 7807?
Best practice: 'type': 'https://api.example.com/errors/insufficient-funds' — a real URL consumers can visit to read about the error. The page should explain: what causes it, how to reproduce it, how to resolve it, and example responses. 'about:blank' is valid RFC 7807 (it means the title/status alone describe the problem) but loses the self-documenting benefit. Generic types should only be used when no additional documentation is needed.
6 / 22
Reviewer: 'This response is great, but the `detail` field just says 'Invalid input'. It's not very helpful for debugging. Can you provide more context?
You: 'I followed the RFC 7807 guidelines and included a descriptive detail message.'
This scenario highlights a common misunderstanding about RFC 7807. The `detail` field is *specifically* designed for providing human-readable context around an error. While standardized codes are useful for automated consumption, the detail field allows developers to understand *why* the error occurred, aiding in debugging and troubleshooting. Options A and C suggest overly restrictive approaches that go against the intended purpose of the `detail` field.
7 / 22
Reviewer: 'The response is well-structured, but the `code` field here (400) isn't specific enough. We need to clearly identify *what* went wrong with the request. It's not immediately obvious why this operation failed. PR Description: 'I've updated the error response to include a more granular HTTP status code and a detailed explanation of the validation failure.'
Which of the following best describes the purpose of the `code` field in an RFC 7807 Problem Details response, as intended by this conversation?
The `code` field in RFC 7807 is designed to represent a specific error *category* or operation failure. It should correspond to an HTTP status code (e.g., 400 for Bad Request), but more importantly, it allows clients to programmatically differentiate between various errors without parsing the entire `detail` message. Using a consistent `code` enables automated error handling and logging, which is crucial in robust API design – simply stating 'Invalid Input' within the `detail` isn't sufficient for programmatic responses.
8 / 22
During a code review, a colleague pointed out that the `code` field in our API error response (a 400 Bad Request) was too generic. They suggested it didn't clearly communicate *what* specifically caused the validation failure. The conversation highlights the importance of granular HTTP status codes and detailed explanations within RFC 7807 Problem Details responses. Which of the following best describes the purpose of the `code` field in an RFC 7807 response, as intended by this feedback?
The `code` field in RFC 7807 is intended to be a more specific HTTP status code than just 400. It's not meant for general human understanding of the error; instead, it's designed to signal *what* kind of validation or operation failed. This allows clients to implement tailored responses based on the precise nature of the issue, rather than relying solely on the generic 'Invalid input' message in the `detail` field. The goal is improved debugging and client-side error handling.
9 / 22
Reviewer: 'This response is great, but the `detail` field just says 'Invalid input'. It's not very helpful for debugging. Can you provide more context?
You: 'I followed the RFC 7807 guidelines and included a descriptive detail message.'
This scenario highlights a common misunderstanding about RFC 7807. The `detail` field is *specifically* designed for providing human-readable context around an error. While standardized codes are useful for automated consumption, the detail field allows developers to understand *why* the error occurred, aiding in debugging and troubleshooting. Options A and C suggest overly restrictive approaches that go against the intended purpose of the `detail` field.
10 / 22
Reviewer: 'The response is well-structured, but the `code` field here (400) isn't specific enough. We need to clearly identify *what* went wrong with the request. It's not immediately obvious why this operation failed. PR Description: 'I've updated the error response to include a more granular HTTP status code and a detailed explanation of the validation failure.'
Which of the following best describes the purpose of the `code` field in an RFC 7807 Problem Details response, as intended by this conversation?
The `code` field in RFC 7807 is designed to represent a specific error *category* or operation failure. It should correspond to an HTTP status code (e.g., 400 for Bad Request), but more importantly, it allows clients to programmatically differentiate between various errors without parsing the entire `detail` message. Using a consistent `code` enables automated error handling and logging, which is crucial in robust API design – simply stating 'Invalid Input' within the `detail` isn't sufficient for programmatic responses.
11 / 22
During a code review, a colleague pointed out that the `code` field in our API error response (a 400 Bad Request) was too generic. They suggested it didn't clearly communicate *what* specifically caused the validation failure. The conversation highlights the importance of granular HTTP status codes and detailed explanations within RFC 7807 Problem Details responses. Which of the following best describes the purpose of the `code` field in an RFC 7807 response, as intended by this feedback?
The `code` field in RFC 7807 is intended to be a more specific HTTP status code than just 400. It's not meant for general human understanding of the error; instead, it's designed to signal *what* kind of validation or operation failed. This allows clients to implement tailored responses based on the precise nature of the issue, rather than relying solely on the generic 'Invalid input' message in the `detail` field. The goal is improved debugging and client-side error handling.
12 / 22
Reviewer: 'This response is great, but the `detail` field just says 'Invalid input'. It's not very helpful for debugging. Can you provide more context?
You: 'I followed the RFC 7807 guidelines and included a descriptive detail message.'
This scenario highlights a common misunderstanding about RFC 7807. The `detail` field is *specifically* designed for providing human-readable context around an error. While standardized codes are useful for automated consumption, the detail field allows developers to understand *why* the error occurred, aiding in debugging and troubleshooting. Options A and C suggest overly restrictive approaches that go against the intended purpose of the `detail` field.
13 / 22
Reviewer: 'The response is well-structured, but the `code` field here (400) isn't specific enough. We need to clearly identify *what* went wrong with the request. It's not immediately obvious why this operation failed. PR Description: 'I've updated the error response to include a more granular HTTP status code and a detailed explanation of the validation failure.'
Which of the following best describes the purpose of the `code` field in an RFC 7807 Problem Details response, as intended by this conversation?
The `code` field in RFC 7807 is designed to represent a specific error *category* or operation failure. It should correspond to an HTTP status code (e.g., 400 for Bad Request), but more importantly, it allows clients to programmatically differentiate between various errors without parsing the entire `detail` message. Using a consistent `code` enables automated error handling and logging, which is crucial in robust API design – simply stating 'Invalid Input' within the `detail` isn't sufficient for programmatic responses.
14 / 22
During a code review, a colleague pointed out that the `code` field in our API error response (a 400 Bad Request) was too generic. They suggested it didn't clearly communicate *what* specifically caused the validation failure. The conversation highlights the importance of granular HTTP status codes and detailed explanations within RFC 7807 Problem Details responses. Which of the following best describes the purpose of the `code` field in an RFC 7807 response, as intended by this feedback?
The `code` field in RFC 7807 is intended to be a more specific HTTP status code than just 400. It's not meant for general human understanding of the error; instead, it's designed to signal *what* kind of validation or operation failed. This allows clients to implement tailored responses based on the precise nature of the issue, rather than relying solely on the generic 'Invalid input' message in the `detail` field. The goal is improved debugging and client-side error handling.
15 / 22
Reviewer: 'This response is great, but the `detail` field just says 'Invalid input'. It's not very helpful for debugging. Can you provide more context?
You: 'I followed the RFC 7807 guidelines and included a descriptive detail message.'
This scenario highlights a common misunderstanding about RFC 7807. The `detail` field is *specifically* designed for providing human-readable context around an error. While standardized codes are useful for automated consumption, the detail field allows developers to understand *why* the error occurred, aiding in debugging and troubleshooting. Options A and C suggest overly restrictive approaches that go against the intended purpose of the `detail` field.
16 / 22
Reviewer: 'The response is well-structured, but the `code` field here (400) isn't specific enough. We need to clearly identify *what* went wrong with the request. It's not immediately obvious why this operation failed. PR Description: 'I've updated the error response to include a more granular HTTP status code and a detailed explanation of the validation failure.'
Which of the following best describes the purpose of the `code` field in an RFC 7807 Problem Details response, as intended by this conversation?
The `code` field in RFC 7807 is designed to represent a specific error *category* or operation failure. It should correspond to an HTTP status code (e.g., 400 for Bad Request), but more importantly, it allows clients to programmatically differentiate between various errors without parsing the entire `detail` message. Using a consistent `code` enables automated error handling and logging, which is crucial in robust API design – simply stating 'Invalid Input' within the `detail` isn't sufficient for programmatic responses.
17 / 22
During a code review, a colleague pointed out that the `code` field in our API error response (a 400 Bad Request) was too generic. They suggested it didn't clearly communicate *what* specifically caused the validation failure. The conversation highlights the importance of granular HTTP status codes and detailed explanations within RFC 7807 Problem Details responses. Which of the following best describes the purpose of the `code` field in an RFC 7807 response, as intended by this feedback?
The `code` field in RFC 7807 is intended to be a more specific HTTP status code than just 400. It's not meant for general human understanding of the error; instead, it's designed to signal *what* kind of validation or operation failed. This allows clients to implement tailored responses based on the precise nature of the issue, rather than relying solely on the generic 'Invalid input' message in the `detail` field. The goal is improved debugging and client-side error handling.
18 / 22
Sarah, a senior developer, is reviewing a new API endpoint. She comments: 'The error response for invalid user IDs (400) just says 'Invalid data'. It's not actionable. We need to tell the client *which* ID was bad.' Which of the following best describes Sarah's concern regarding RFC 7807 and error design?
Sarah's feedback highlights the importance of designing API errors with both human and machine consumers in mind. RFC 7807 emphasizes providing specific details within the `detail` field to help clients understand *why* an error occurred, allowing for targeted recovery actions. The options presented misinterpret the role of each field – the `code` is for a clear indication, while the `detail` contains specifics.
19 / 22
During a stand-up meeting, Mark mentions that their team's API error responses are using consistent HTTP status codes but lack detailed information in the `detail` field. His manager asks: 'What is the primary purpose of the 'instance' field as defined in RFC 7807?'
The 'instance' field in RFC 7807 is a unique identifier assigned to each error response. This allows for consistent tracking and debugging across different systems and services – crucial for effective monitoring and troubleshooting. The other options describe related but distinct elements of an API error response.
20 / 22
You're documenting a new API endpoint in OpenAPI. You've defined a 400 Bad Request error with a `code` of 'validation_failed'. A junior developer asks: 'What is the recommended practice for the 'type' URI within RFC 7807 when describing this error response?'
RFC 7807 recommends that the 'type' URI within an OpenAPI definition should mirror the HTTP status code of the error (e.g., '400'). This ensures consistency and clarity in how clients interpret the response format. The other options are either incorrect or misinterpret the role of this field.
21 / 22
In a Slack message discussing API error handling, David writes: 'We're using a standard 400 response with a `code` of 'resource_not_found' and a `detail` that says 'The requested resource does not exist.' But our client keeps getting this error even when the resource *does* exist – it's baffling!' What is David most likely pointing out?
David's message highlights a common issue: insufficient details in the `detail` field can obscure the true cause of an error. A well-designed response, as per RFC 7807, would provide more specific information to guide debugging and recovery attempts – this is what's missing here.
22 / 22
You're reviewing a PR that implements error responses for an API. The proposed response for a failed authentication attempt (401) includes only the `code` field set to 'auth_failed'. A reviewer comments: 'This is too vague! The client needs more information to understand *why* authentication failed.' What's the most appropriate action you should take?
The reviewer's feedback aligns perfectly with RFC 7807's recommendation: detailed information within the `detail` field is crucial for effective error handling. Adding a descriptive `detail` would significantly improve the client's ability to understand and address the authentication failure – this is the correct course of action.
What will I practice in "API Error Response Writing — RFC 7807 & Error Design"?
This is an API Spec Writing exercise set. It walks through 22 scenario-based multiple-choice questions built around real usage of API Spec Writing terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 22 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the API Spec Writing vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more API Spec Writing exercises?
See the API Spec Writing exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — API Spec Writing vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.