Problem Details (RFC 7807) format in Rest API - Step-by-Step Execution

Concept Flow - Problem Details (RFC 7807) format

Client sends request

↓

Server detects error

↓

Server creates Problem Details JSON

↓

Server sends response with JSON

↓

Client reads error details

↓

Client handles error accordingly

The client sends a request; if the server finds an error, it sends back a JSON with problem details following RFC 7807; the client reads and handles the error.

Execution Sample

Rest API

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/transactions/abc"
}

This JSON shows a problem details response for a credit error with type, title, status, detail, and instance fields.

Execution Table

Step	Action	Field Created	Value	Purpose
1	Detect error	type	https://example.com/probs/out-of-credit	URI identifying error type
2	Add short summary	title	You do not have enough credit.	Human-readable error title
3	Add HTTP status	status	403	HTTP status code for error
4	Add detailed message	detail	Your current balance is 30, but that costs 50.	Detailed explanation of error
5	Add instance URI	instance	/account/12345/transactions/abc	URI identifying specific occurrence
6	Send response	JSON body	Full JSON object	Client receives error details
7	Client reads	fields	All above	Client can handle error based on info
8	End	-	-	Process complete

💡 All problem details fields created and sent; client receives and processes error.

Variable Tracker

Field	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	Final
type	undefined	https://example.com/probs/out-of-credit	https://example.com/probs/out-of-credit	https://example.com/probs/out-of-credit	https://example.com/probs/out-of-credit	https://example.com/probs/out-of-credit	https://example.com/probs/out-of-credit
title	undefined	undefined	You do not have enough credit.	You do not have enough credit.	You do not have enough credit.	You do not have enough credit.	You do not have enough credit.
status	undefined	undefined	undefined	403	403	403	403
detail	undefined	undefined	undefined	undefined	Your current balance is 30, but that costs 50.	Your current balance is 30, but that costs 50.	Your current balance is 30, but that costs 50.
instance	undefined	undefined	undefined	undefined	undefined	/account/12345/transactions/abc	/account/12345/transactions/abc

Key Moments - 3 Insights

Why do we use a URI in the 'type' field instead of just a short text?

The 'type' field uses a URI to uniquely identify the error type so clients can programmatically recognize and handle specific errors, as shown in execution_table step 1.

Is the 'status' field required and why is it useful?

Yes, 'status' is recommended to match the HTTP status code so clients can quickly understand the error category, as seen in execution_table step 3.

What is the purpose of the 'instance' field?

The 'instance' field gives a URI pointing to the specific occurrence of the problem, helping clients or support teams locate the exact error case, as added in execution_table step 5.

Visual Quiz - 3 Questions

Look at the execution_table at step 4, what is the value of the 'detail' field?

A 403

B You do not have enough credit.

C Your current balance is 30, but that costs 50.

D https://example.com/probs/out-of-credit

💡 Hint

Check the 'detail' field value in execution_table row with step 4.

At which step is the HTTP status code added to the problem details JSON?

A Step 3

B Step 2

C Step 5

D Step 1

💡 Hint

Look for the 'status' field creation in execution_table.

If the 'instance' field was missing, which step would be skipped?

A Step 4

B Step 5

C Step 2

D Step 3

💡 Hint

Check which step adds the 'instance' field in execution_table.

Concept Snapshot

Problem Details (RFC 7807) format:
- JSON object with fields: type (URI), title (short text), status (HTTP code), detail (long text), instance (URI)
- Used to send standardized error info in REST APIs
- Helps clients understand and handle errors clearly
- 'type' URI uniquely identifies error kind
- 'status' matches HTTP response code
- 'instance' points to specific error occurrence

Full Transcript

This visual execution shows how a REST API server creates and sends a Problem Details JSON response following RFC 7807 when an error occurs. The server detects an error, then builds a JSON object step-by-step adding fields: 'type' as a URI to identify the error type, 'title' as a short human-readable summary, 'status' as the HTTP status code, 'detail' with a detailed explanation, and 'instance' as a URI pointing to the specific error occurrence. The client receives this JSON and can read these fields to understand and handle the error properly. Key points include the use of URIs for 'type' and 'instance' to uniquely identify errors and occurrences, and matching 'status' to the HTTP code. The execution table traces each step of building the JSON, and the variable tracker shows how each field is added. The quiz questions check understanding of field values and their creation steps.

Practice

1. What is the main purpose of the Problem Details (RFC 7807) format in REST APIs?

easy

A. To speed up API response times

B. To standardize error responses so clients can understand errors better

C. To encrypt API responses for security

D. To format successful data responses uniformly

Solution

1. Step 1: Understand the role of Problem Details format

   The format is designed to provide a consistent way to report errors in APIs.

2. Step 2: Identify the main benefit

   It helps clients understand and handle errors better by standardizing error responses.

3. Final Answer:

   To standardize error responses so clients can understand errors better -> Option B

4. Quick Check:

   Purpose = Standardize error responses [OK]

Hint: Remember: Problem Details = standardized error info [OK]

Common Mistakes:

• Confusing error format with data encryption
• Thinking it speeds up API responses
• Assuming it formats successful responses

2. Which of the following is a REQUIRED field in the Problem Details JSON object according to RFC 7807?

easy

A. type

B. status

C. detail

D. instance

Solution

1. Step 1: Recall required fields in RFC 7807

   The RFC requires the "type" field to identify the error type URI.

2. Step 2: Check other fields

   Fields like "status", "detail", and "instance" are optional but recommended.

3. Final Answer:

   type -> Option A

4. Quick Check:

   Required field = type [OK]

Hint: Only 'type' is mandatory in Problem Details [OK]

Common Mistakes:

• Assuming 'status' is required
• Confusing 'detail' as mandatory
• Thinking 'instance' is always needed

3. Given this Problem Details JSON response:

{"type": "https://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "status": 403, "detail": "Your current balance is 30, but that costs 50.", "instance": "/account/12345/msgs/abc"}

What is the HTTP status code indicated?

medium

A. 403

B. 404

C. 200

D. 500

Solution

1. Step 1: Locate the status field in JSON

   The JSON has "status": 403, which indicates the HTTP status code.

2. Step 2: Understand the meaning of 403

   403 means Forbidden, matching the error about insufficient credit.

3. Final Answer:

   403 -> Option A

4. Quick Check:

   Status code = 403 [OK]

Hint: Look for 'status' field for HTTP code [OK]

Common Mistakes:

• Confusing status with 'detail' content
• Picking 200 as success code
• Ignoring the numeric status field

4. You receive this Problem Details JSON:

{"title": "Invalid input", "status": 400, "detail": "Missing required field 'name'"}

What is missing that violates RFC 7807 requirements?

medium

A. The 'title' field should be a URL

B. The 'status' field should be a string

C. The 'detail' field should be omitted

D. The 'type' field is missing

Solution

1. Step 1: Check required fields in the JSON

   The 'type' field is required by RFC 7807 but is missing here.

2. Step 2: Validate other fields

   'status' is correctly a number, 'detail' and 'title' are valid types.

3. Final Answer:

   The 'type' field is missing -> Option D

4. Quick Check:

   Missing required field = type [OK]

Hint: Always include 'type' field in Problem Details [OK]

Common Mistakes:

• Thinking 'status' must be string
• Removing 'detail' field
• Assuming 'title' must be URL

5. You want to create a Problem Details response for a rate limit error. Which JSON object correctly follows RFC 7807 and clearly informs the client about the error?

hard

A. {"type": "rate-limit", "title": "Error", "status": 429, "detail": "Limit reached"}

B. {"title": "Rate limit exceeded", "status": "429", "detail": "Too many requests", "instance": "/api/v1/resource"}

C. {"type": "https://example.com/probs/rate-limit", "title": "Rate limit exceeded", "status": 429, "detail": "You have sent too many requests in a short time.", "instance": "/api/v1/resource"}

D. {"type": "https://example.com/probs/rate-limit", "title": "Rate limit exceeded", "status": 200, "detail": "Too many requests"}

Solution

1. Step 1: Check required fields and correct types

   {"type": "https://example.com/probs/rate-limit", "title": "Rate limit exceeded", "status": 429, "detail": "You have sent too many requests in a short time.", "instance": "/api/v1/resource"} includes 'type' as a URI, 'title', numeric 'status' 429, 'detail', and 'instance' fields correctly.

2. Step 2: Validate status code and clarity

   Status 429 means Too Many Requests, matching the error. Other options have missing or wrong fields or wrong status codes.

3. Final Answer:

   {"type": "https://example.com/probs/rate-limit", "title": "Rate limit exceeded", "status": 429, "detail": "You have sent too many requests in a short time.", "instance": "/api/v1/resource"} -> Option C

4. Quick Check:

   Correct fields and status = {"type": "https://example.com/probs/rate-limit", "title": "Rate limit exceeded", "status": 429, "detail": "You have sent too many requests in a short time.", "instance": "/api/v1/resource"} [OK]

Hint: Use URI in 'type' and correct numeric 'status' [OK]

Common Mistakes:

• Using string instead of number for status
• Missing 'type' or using non-URI string
• Wrong HTTP status code for error