Skip to main content

Error Handling

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:

{
"data": { ... },
}

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:

{
"data": { ... } | null,
"errors": [...],
}

For example, the following query contains invalid cursor value:

{
vessels(first: 3, after: "bla-bla") {
nodes {
id
staticData {
mmsi
callsign
}
}
}
}

which yields the the following response:

{
"data": null,
"errors": [
{
"message": "Invalid cursor provided for the after parameter: a",
"locations": [{ "line": 2, "column": 3 }],
"path": ["vessels"],
"extensions": {
"code": "BAD_USER_INPUT"
}
}
],
"extensions": {
"requestId": "7246b710-145d-4528-9c74-972287dc713a"
}
}

Error Format#

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": "Invalid cursor provided for the after parameter: a",
"locations": [{ "line": 2, "column": 3 }],
"path": ["vessels"],
"extensions": {
"code": "BAD_USER_INPUT"
}
}

Where:

  • 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 code.

Note

  • Object errors.extensions (described above) is not to be confused with the top-level object extensions that provides additional useful information about the request itself such as requestId
  • The contents of both extensions fields may be subject to change in the future releases of GraphQL API.

Standard Error Codes#

Spire provides standard error codes similar to the HTTP error codes where each error code indicates a specific class of errors.

CodeDescription

GRAPHQL_PARSE_FAILED

The GraphQL operation string contains a syntax error.

GRAPHQL_VALIDATION_FAILED

The GraphQL operation is not valid against the server's schema.

BAD_USER_INPUT

The GraphQL operation includes an invalid value for a field argument. Error with this code most commonly occurs:

  • Arguments have incorrect type. For example mmsi was submitted as a string, but not an integer.
  • Validation failed on the value. For example WKT strings contain syntax errors.
  • Impossible to perform an operation for given arguments. For example, it is impossible to calculate routes for given arguments.

UNAUTHENTICATED

The server failed to authenticate a user. For example when the Authorization header doesn't present in the request.

FORBIDDEN

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.

TIMEOUT_ERROR

Query result didn't come within the timeout limit.

SERVICE_UNAVAILABLE

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.

TOO_MANY_REQUESTS

The request was rate-limited. This error is added alongside with response in case it was rate-limited by the GraphQL server.

INTERNAL_SERVER_ERROR

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.

Troubleshooting#

  • GRAPHQL_PARSE_FAILED or GRAPHQL_VALIDATION_FAILED please check the correctness of the GraphQL query. You can easily do it in the playground.
  • UNAUTHENTICATED please verify your authentication token. Please, check if your token is correct and valid.
  • FORBIDDEN the query contains access to non-authorized parts of the schema.
  • BAD_USER_INPUT please check the query arguments. Be sure that argument variables for scalars has correct format.
  • TIMEOUT_ERROR or SERVICE_UNAVAILABLE you may try to retry request
  • INTERNAL_SERVER_ERROR please communicate it with the query and requestId to the Data Operations team for investigation.
  • TOO_MANY_REQUESTS please adjust the request rate per minute. See rate limiting.