Custom error extensions in GraphQL - Step-by-Step Execution

Concept Flow - Custom error extensions

GraphQL Query Received

↓

Execute Resolver

↓

Error Occurs?

No→Return Data

Yes↓

Create Error Object

↓

Add Custom Extensions

↓

Return Error with Extensions

When a GraphQL query runs, if an error happens, a custom extensions object can be added to the error before sending it back.

Execution Sample

GraphQL

throw new GraphQLError('Not found', {
  extensions: { code: 'NOT_FOUND', detail: 'User ID missing' }
});

This code throws a GraphQL error with a custom extensions object containing extra info.

Execution Table

Step	Action	Error Object State	Extensions Added	Result Sent
1	Query received	No error yet	None	No response yet
2	Resolver runs	No error yet	None	No response yet
3	Error thrown	Error message: 'Not found'	None	No response yet
4	Add extensions	Error message: 'Not found'	{ code: 'NOT_FOUND', detail: 'User ID missing' }	No response yet
5	Return error	Error with extensions	{ code: 'NOT_FOUND', detail: 'User ID missing' }	Error response sent

💡 Error with custom extensions returned to client

Variable Tracker

Variable	Start	After Step 3	After Step 4	Final
error	undefined	{ message: 'Not found' }	{ message: 'Not found', extensions: { code: 'NOT_FOUND', detail: 'User ID missing' } }	Returned to client with extensions

Key Moments - 2 Insights

Why do we add extensions to the error object?

Extensions provide extra structured info about the error, like error codes or details, which helps clients handle errors better. See execution_table step 4.

Does the error message change when we add extensions?

No, the main error message stays the same. Extensions add extra info without changing the message. See execution_table steps 3 and 4.

Visual Quiz - 3 Questions

Look at the execution_table, at which step are extensions added to the error?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Check the 'Extensions Added' column in execution_table rows

According to variable_tracker, what is the state of 'error' after step 3?

A { message: 'Not found', extensions: {...} }

B undefined

C { message: 'Not found' }

D Returned to client

💡 Hint

Look at the 'After Step 3' column for 'error' in variable_tracker

If we did not add extensions, what would the client receive?

A Error with only message, no extensions

B Error with default extensions

C Error with no message

D No error at all

💡 Hint

Refer to execution_table step 3 where error is thrown without extensions

Concept Snapshot

GraphQL errors can include a custom 'extensions' object.
Use 'extensions' to add extra info like error codes.
Throw errors with 'new GraphQLError(message, { extensions })'.
Clients receive both message and extensions.
Extensions help clients handle errors better.

Full Transcript

When a GraphQL query runs, the server executes resolvers. If an error happens, the server creates an error object with a message. We can add a custom 'extensions' object to this error to provide extra details like error codes or descriptions. This helps clients understand and handle errors better. The error with extensions is then sent back in the response. The main error message stays the same; extensions just add more info. This process ensures clear and structured error reporting in GraphQL APIs.

Practice

1. What is the main purpose of using extensions in GraphQL error responses?

easy

A. To change the data returned by the query

B. To hide errors from the client

C. To speed up the query execution

D. To provide extra information like error codes and details

Solution

1. Step 1: Understand the role of error extensions

   Extensions add extra info to errors, such as codes or metadata.

2. Step 2: Compare with other options

   Extensions do not change data, speed, or hide errors; they enrich error info.

3. Final Answer:

   To provide extra information like error codes and details -> Option D

4. Quick Check:

   Extensions add info = B [OK]

Hint: Extensions add details to errors, not data or speed [OK]

Common Mistakes:

• Thinking extensions change query data
• Assuming extensions hide errors
• Confusing extensions with performance tools

2. Which of the following is the correct way to add a custom error extension in a GraphQL error object?

easy

A. { message: 'Error', extensions: ['BAD_REQUEST'] }

B. { message: 'Error', code: 'BAD_REQUEST' }

C. { message: 'Error', extensions: { code: 'BAD_REQUEST' } }

D. { error: 'Error', extensions: 'BAD_REQUEST' }

Solution

1. Step 1: Identify correct error object structure

   The error object must have a message and an extensions object with code inside.

2. Step 2: Check each option's syntax

   { message: 'Error', extensions: { code: 'BAD_REQUEST' } } correctly nests code inside extensions; others misuse or misplace fields.

3. Final Answer:

   { message: 'Error', extensions: { code: 'BAD_REQUEST' } } -> Option C

4. Quick Check:

   Extensions is an object with code = D [OK]

Hint: Extensions must be an object with keys like code [OK]

Common Mistakes:

• Putting code outside extensions
• Using extensions as a string or array
• Misnaming fields like error instead of message

3. Given this GraphQL error response:

{"errors":[{"message":"Not found","extensions":{"code":"NOT_FOUND","timestamp":"2024-06-01T12:00:00Z"}}]}

What will the client see in the extensions field?

medium

A. {"code":"NOT_FOUND","timestamp":"2024-06-01T12:00:00Z"}

B. "Not found"

C. {"message":"Not found"}

D. An empty object {}

Solution

1. Step 1: Locate the extensions field in the error

   The extensions field contains code and timestamp as key-value pairs.

2. Step 2: Understand what client receives

   The client sees the extensions object exactly as given, with code and timestamp.

3. Final Answer:

   {"code":"NOT_FOUND","timestamp":"2024-06-01T12:00:00Z"} -> Option A

4. Quick Check:

   Extensions content = A [OK]

Hint: Extensions field shows all custom error details as object [OK]

Common Mistakes:

• Confusing message with extensions
• Expecting extensions to be a string
• Ignoring extra fields like timestamp

4. You wrote this error response in your GraphQL server:

{ message: 'Unauthorized', extensions: 'AUTH_ERROR' }

Why does this cause a problem?

medium

A. Extensions must be an object, not a string

B. Message cannot be 'Unauthorized'

C. Extensions field is missing

D. The error object must not have extensions

Solution

1. Step 1: Check the type of extensions field

   Extensions must be an object with key-value pairs, not a string.

2. Step 2: Identify the error cause

   Using a string for extensions causes syntax or runtime errors in GraphQL.

3. Final Answer:

   Extensions must be an object, not a string -> Option A

4. Quick Check:

   Extensions type error = A [OK]

Hint: Extensions must always be an object, never a string [OK]

Common Mistakes:

• Using string instead of object for extensions
• Ignoring GraphQL error format rules
• Assuming message content causes error

5. You want to send a GraphQL error with a custom extension that includes an error code and a retry flag set to false. Which of these error objects correctly implements this?

hard

A. { message: 'Timeout', extensions: { code: 'TIMEOUT', retry: 0 } }

B. { message: 'Timeout', extensions: { code: 'TIMEOUT', retry: false } }

C. { message: 'Timeout', extensions: { code: 'TIMEOUT', retry: 'no' } }

D. { message: 'Timeout', extensions: { code: 'TIMEOUT', retry: null } }

Solution

1. Step 1: Check the data types for extensions fields

   The retry flag should be a boolean false, not string or null or number.

2. Step 2: Validate each option's retry value

   { message: 'Timeout', extensions: { code: 'TIMEOUT', retry: false } } uses boolean false correctly; others use wrong types.

3. Final Answer:

   { message: 'Timeout', extensions: { code: 'TIMEOUT', retry: false } } -> Option B

4. Quick Check:

   Boolean retry flag = C [OK]

Hint: Use boolean false for retry, not string or null [OK]

Common Mistakes:

• Using string 'no' instead of boolean false
• Using null or 0 for boolean flags
• Ignoring correct data types in extensions