@@ -125,6 +125,17 @@ error is a map.
125
125
If no errors were encountered during the requested operation, the ` errors `
126
126
entry should not be present in the result.
127
127
128
+ If the ` data ` entry in the response is not present, the ` errors `
129
+ entry in the response must not be empty. It must contain at least one error.
130
+ The errors it contains should indicate why no data was able to be returned.
131
+
132
+ If the ` data ` entry in the response is present (including if it is the value
133
+ {null}), the ` errors ` entry in the response may contain any errors that
134
+ occurred during execution. If errors occurred during execution, it should
135
+ contain those errors.
136
+
137
+ ** Error result format**
138
+
128
139
Every error must contain an entry with the key ` message ` with a string
129
140
description of the error intended for the developer as a guide to understand
130
141
and correct the error.
@@ -135,14 +146,103 @@ locations, where each location is a map with the keys `line` and `column`, both
135
146
positive numbers starting from ` 1 ` which describe the beginning of an
136
147
associated syntax element.
137
148
149
+ If an error can be associated to a particular field in the GraphQL result, it
150
+ must contain an entry with the key ` path ` that details the path of the
151
+ response field which experienced the error. This allows clients to identify
152
+ whether a ` null ` result is intentional or caused by a runtime error.
153
+
154
+ This field should be a list of path segments starting at the root of the
155
+ response and ending with the field associated with the error. Path segments
156
+ that represent fields should be strings, and path segments that
157
+ represent list indices should be 0-indexed integers. If the error happens
158
+ in an aliased field, the path to the error should use the aliased name, since
159
+ it represents a path in the response, not in the query.
160
+
161
+ For example, if fetching one of the friends' names fails in the following
162
+ query:
163
+
164
+ ``` graphql
165
+ {
166
+ hero (episode : $episode ) {
167
+ name
168
+ heroFriends : friends {
169
+ id
170
+ name
171
+ }
172
+ }
173
+ }
174
+ ```
175
+
176
+ The response might look like:
177
+
178
+ ``` js
179
+ {
180
+ " errors" : [
181
+ {
182
+ " message" : " Name for character with ID 1002 could not be fetched." ,
183
+ " locations" : [ { " line" : 6 , " column" : 7 } ],
184
+ " path" : [ " hero" , " heroFriends" , 1 , " name" ]
185
+ }
186
+ ],
187
+ " data" : {
188
+ " hero" : {
189
+ " name" : " R2-D2" ,
190
+ " heroFriends" : [
191
+ {
192
+ " id" : " 1000" ,
193
+ " name" : " Luke Skywalker"
194
+ },
195
+ {
196
+ " id" : " 1002" ,
197
+ " name" : null
198
+ },
199
+ {
200
+ " id" : " 1003" ,
201
+ " name" : " Leia Organa"
202
+ }
203
+ ]
204
+ }
205
+ }
206
+ }
207
+ ```
208
+
209
+ If the field which experienced an error was declared as ` Non-Null ` , the ` null `
210
+ result will bubble up to the next nullable field. In that case, the ` path `
211
+ for the error should include the full path to the result field where the error
212
+ occurred, even if that field is not present in the response.
213
+
214
+ For example, if the ` name ` field from above had declared a ` Non-Null ` return
215
+ type in the schema, the result would look different but the error reported would
216
+ be the same:
217
+
218
+ ``` js
219
+ {
220
+ " errors" : [
221
+ {
222
+ " message" : " Name for character with ID 1002 could not be fetched." ,
223
+ " locations" : [ { " line" : 6 , " column" : 7 } ],
224
+ " path" : [ " hero" , " heroFriends" , 1 , " name" ]
225
+ }
226
+ ],
227
+ " data" : {
228
+ " hero" : {
229
+ " name" : " R2-D2" ,
230
+ " heroFriends" : [
231
+ {
232
+ " id" : " 1000" ,
233
+ " name" : " Luke Skywalker"
234
+ },
235
+ null ,
236
+ {
237
+ " id" : " 1003" ,
238
+ " name" : " Leia Organa"
239
+ }
240
+ ]
241
+ }
242
+ }
243
+ }
244
+ ```
245
+
138
246
GraphQL servers may provide additional entries to error as they choose to
139
247
produce more helpful or machine-readable errors, however future versions of the
140
248
spec may describe additional entries to errors.
141
-
142
- If the ` data ` entry in the response is ` null ` or not present, the ` errors `
143
- entry in the response must not be empty. It must contain at least one error.
144
- The errors it contains should indicate why no data was able to be returned.
145
-
146
- If the ` data ` entry in the response is not ` null ` , the ` errors ` entry in the
147
- response may contain any errors that occurred during execution. If errors
148
- occurred during execution, it should contain those errors.
0 commit comments