API Error Response Documentation — Vocabulary and Writing
Learn to document API errors: error codes, error messages, resolution hints, and problem detail format.
0 / 14 completed
1 / 14
What should a well-documented API error response include?
Good error response: status 422, error code VALIDATION_FAILED, message 'The email address format is invalid', field 'user.email', detail 'Email must follow format user@domain.tld', documentation_url '/docs/errors/VALIDATION_FAILED'. This allows: client code to branch on error_code, developers to understand and fix the issue, and users to receive meaningful feedback.
2 / 14
What is the RFC 9457 'Problem Details' format in API error documentation?
RFC 9457 (formerly RFC 7807) Problem Details: type: URI that identifies the error type (points to documentation), title: short summary ('Insufficient Credit'), status: 403, detail: 'Your account has insufficient credit. Current balance: $0.00. Required: $5.00.', instance: /account/transactions/123. Standardized format enables consistent error handling across different APIs.
3 / 14
What is the difference between 4xx and 5xx error documentation priorities?
4xx documentation priority: clients must handle these — document every expected 4xx with the specific trigger, error code, and resolution. 5xx documentation: clients cannot fix server errors — document the recommended client behavior (retry strategy with exponential backoff, when to surface to user, how to report). Never include internal error details (stack traces, SQL errors) in 5xx responses.
4 / 14
What is 'error code' vs. 'HTTP status code' in API documentation vocabulary?
HTTP 400 covers many different client errors. An API error code within 400 specifies: INVALID_FORMAT (malformed JSON), VALIDATION_FAILED (field constraint violated), MISSING_REQUIRED_FIELD (required field absent). Clients can branch logic on error codes without parsing human-readable messages — which may change across API versions.
5 / 14
What is 'retry guidance' in API error response documentation?
Retry guidance prevents both missed opportunities (not retrying retryable errors) and wasted work (retrying non-retryable errors). Document: retryable errors (5xx, 429, 408), non-retryable errors (400, 401, 403, 404), retry strategy (exponential backoff with jitter for 5xx), and maximum retry count. The Retry-After header makes 429 handling explicit.
6 / 14
John from QA just left a comment on your PR describing the response from our PaymentGatewayService. He's asking for clarification. Below is his comment:
"The response says 'Invalid request parameters'. But what exactly *is* 'invalid'? Does it mean we need to provide different data, or are the fields just wrong? And should I log this as a bug?"
Which of the following best describes how you should respond to John, focusing on clear documentation terminology?
John is struggling with the abstract term 'invalid' in the error response. The correct approach is to explain that 'invalid' refers specifically to data type and format issues (e.g., wrong data types, missing required fields). It's crucial to guide him towards understanding where these validation rules are documented – in this case, the Swagger definition or API schema, which provides concrete examples of what constitutes a valid request. Simply stating the term 'invalid' doesn't provide actionable guidance and likely contributes to his confusion.
7 / 14
John from QA just left a comment on your PR describing the response from our PaymentGatewayService. He's asking for clarification. Below is his comment:
"The response says 'Invalid request parameters'. But what exactly *is* 'invalid'? Does it mean we need to provide different data, or are the fields just wrong? And should I log this as a bug?"
Which of the following best describes how you should respond to John, focusing on clear documentation terminology?
John is struggling with the abstract term 'invalid' in the error response. The correct approach is to explain that 'invalid' refers specifically to data type and format issues (e.g., wrong data types, missing required fields). It's crucial to guide him towards understanding where these validation rules are documented – in this case, the Swagger definition or API schema, which provides concrete examples of what constitutes a valid request. Simply stating the term 'invalid' doesn't provide actionable guidance and likely contributes to his confusion.
8 / 14
John from QA just left a comment on your PR describing the response from our PaymentGatewayService. He's asking for clarification. Below is his comment:
"The response says 'Invalid request parameters'. But what exactly *is* 'invalid'? Does it mean we need to provide different data, or are the fields just wrong? And should I log this as a bug?"
Which of the following best describes how you should respond to John, focusing on clear documentation terminology?
John is struggling with the abstract term 'invalid' in the error response. The correct approach is to explain that 'invalid' refers specifically to data type and format issues (e.g., wrong data types, missing required fields). It's crucial to guide him towards understanding where these validation rules are documented – in this case, the Swagger definition or API schema, which provides concrete examples of what constitutes a valid request. Simply stating the term 'invalid' doesn't provide actionable guidance and likely contributes to his confusion.
9 / 14
John from QA just left a comment on your PR describing the response from our PaymentGatewayService. He's asking for clarification. Below is his comment:
"The response says 'Invalid request parameters'. But what exactly *is* 'invalid'? Does it mean we need to provide different data, or are the fields just wrong? And should I log this as a bug?"
Which of the following best describes how you should respond to John, focusing on clear documentation terminology?
John is struggling with the abstract term 'invalid' in the error response. The correct approach is to explain that 'invalid' refers specifically to data type and format issues (e.g., wrong data types, missing required fields). It's crucial to guide him towards understanding where these validation rules are documented – in this case, the Swagger definition or API schema, which provides concrete examples of what constitutes a valid request. Simply stating the term 'invalid' doesn't provide actionable guidance and likely contributes to his confusion.
10 / 14
Sarah, a junior developer, is drafting the documentation for a new API endpoint. A user reports an error with a 400 response. Which of the following descriptions would be MOST helpful to include in the response's 'error details' section?
The key here is providing enough detail for the user to understand *why* their request failed. A good response includes a specific 'code' (like `bad_request`) and details about the problematic fields. Options A and C are too vague; option B is ideal because it links to a schema, and option D is unhelpful.
11 / 14
During a code review, Mark points out that the API response for a failed authentication attempt lacks information about *why* the user was denied. Which of the following additions would BEST address his feedback?
'The response should include a field indicating the specific reason for failure, such as 'invalid_password' or 'account_locked'.
Mark is highlighting the need for actionable information. A well-documented error response provides a 'code' (like `invalid_password`) alongside a clear message explaining *why* that code triggered the failure. Option A is too basic; option B isn't an error response element; option C could overwhelm the user, and option D misses a crucial feedback opportunity.
12 / 14
You're writing documentation for a service that returns 500 errors. Which of the following statements best describes the appropriate use of 'retry guidance' in this context?
'The documentation should instruct users to retry their request after a short delay, perhaps 30 seconds, if they encounter a 500 error – assuming the underlying issue is transient.'
500 errors often indicate temporary issues. Retries with a short delay (e.g., 30 seconds) can be effective in these scenarios. However, it's vital to set limits to avoid indefinite retries. Options A and B are too extreme; option C is good but needs the retry limit specified; option D is appropriate for truly critical failures.
13 / 14
During a Slack discussion about API error responses, David asks: 'How do we differentiate between a 401 Unauthorized and a 403 Forbidden response when documenting the endpoint?'
Which of the following explanations is MOST accurate?
'A 401 Unauthorized indicates that the user's credentials are incorrect or missing, while a 403 Forbidden means the user has no permission to access the resource, even with valid credentials.'
The core difference lies in *why* the access was denied. A 401 signifies authentication failure, while a 403 indicates authorization failure – even with correct credentials. Option A is incorrect; option B misrepresents the fundamental distinction; option C prioritizes the HTTP status code over meaningful error details, and option D is simply false.
14 / 14
You are reviewing a PR that includes an API endpoint returning a 201 Created response. The documentation lacks information about what resource was actually created. What's the BEST way to address this in the documentation?
'Include a field in the response body detailing the URI of the newly created resource (e.g., `/users/123`).'
For a `201 Created` response, it's crucial to tell the client *where* the newly created resource can be found. Providing the URI is the standard practice. Options A and B are incomplete; option C is overly complex and not part of an API contract; option D is good but should focus on the most relevant information - the URI.
What will I practice in "API Error Response Documentation — Vocabulary and Writing"?
This is an API Spec Writing exercise set. It walks through 14 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 14 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.