Error Messages

Errors are handled significantly differently in GraphQL than in REST APIs. In REST APIs, errors are usually handled by returning a status code and a message in the response body. In GraphQL, errors are handled by returning a list of errors in the response body. All but the most fatal of errors will return a 200 OK response.

In GraphQL it is the responsibility of the client to determine if the request was successful or not, and handle the errors accordingly.

As already mentioned, GraphQL is strongly typed, and as such, the API will validate the query before executing it. If the query is invalid, the API will return a list of errors in the response body.

So if the query requests a field that does not exist, or the wrong type of argument is provided, the API will reject this request and return a list of errors.

As already mentioned, in the Rate Limiting section above, Cloudshelf performs some analysis of each request to determine whether it fits within our fair-use policy. Should any of those validations fail, a top-level error will be surfaced.

Unlike REST APIs which would usually return a 404 HTTP code when a resource is not found, GraphQL will return a 200 OK response, but the response body will contain null where the resource would normally be.

Depending on the type of mutation, there are a number of different errors that can be returned.

Generally, if the mutation is partly successful the API will return a list of userErrors as part of the response.

If there was a fatal error as part of the mutation, a top level error will be returned.