Handling errors in GraphQL is different compare to other API styles in a several aspects:
- GraphQL response is always
HTTP 200 OK
- GraphQL errors is just data, it's not linked to HTTP error statuses and does not inherit HTTP semantics at all
- It's possible to return query data as well as an array of errors. In this case query data will contain partial results
The successful GraphQL response contains just a
data field with result of the query:
When an error occurs, the GraphQL response will contain an
errors array. In this case
data might be
null or might be an object, but with a complete or partial results, depending on the nature of the error:
For example, the following query contains invalid cursor value:
which yields the the following response:
We use standard error format for the errors which means all errors are having the same structure. Let's explore error from the previous example:
message- string which describes the error
locations- shows where in the query string document this happened
path- is an array of paths leading to the field in error from the root of the query
extensions- is an object with any additional metadata about an error such as an error
errors.extensions(described above) is not to be confused with the top-level object
extensionsthat provides additional useful information about the request itself such as
- The contents of both
extensionsfields may be subject to change in the future releases of GraphQL API.
Spire provides standard error codes similar to the HTTP error codes where each error code indicates a specific class of errors.
The GraphQL operation string contains a syntax error.
The GraphQL operation is not valid against the server's schema.
The GraphQL operation includes an invalid value for a field argument. Error with this code most commonly occurs:
The server failed to authenticate a user. For example when the
Query contains a request to the data which is not authorized by the provided token. For example when you are trying to query vessel characteristics but you don't have access to it.
Query result didn't come within the timeout limit.
One of our services is temporarily unavailable due to some (network) issues. This error code is analogue of HTTP 503 Service Unavailable code and customers might try to retry in this case.
The request was rate-limited. This error is added alongside with response in case it was rate-limited by the GraphQL server.
An unspecified error occurred.
Node: the list of error codes is subject to change in the future releases of GraphQL API. Some codes may be added or removed.
GRAPHQL_VALIDATION_FAILEDplease check the correctness of the GraphQL query. You can easily do it in the playground.
UNAUTHENTICATEDplease verify your authentication token. Please, check if your token is correct and valid.
FORBIDDENthe query contains access to non-authorized parts of the schema.
BAD_USER_INPUTplease check the query arguments. Be sure that argument variables for scalars has correct format.
SERVICE_UNAVAILABLEyou may try to retry request
INTERNAL_SERVER_ERRORplease communicate it with the query and
requestIdto the Data Operations team for investigation.
TOO_MANY_REQUESTSplease adjust the request rate per minute. See rate limiting.