Attention: Our API is in active development. Please ensure to read our Development Notice for important information on potential changes and updates. We appreciate your understanding.

GraphQL Error Handling

In this guide, we will talk about what happens when something goes wrong while you work with the API.

Error handling in GraphQL differs from traditional REST API error handling. GraphQL has its own error handling mechanism that allows for consistent and standardized error responses. This section provides guidance on error handling in GraphQL APIs and highlights the key differences compared to REST.

HTTP Status Codes

GraphQL APIs typically respond with a 200 status code for successful requests. However, there are scenarios where the server may respond with different status codes to indicate specific conditions:

  • Name
    200 Ok
    Type
    Constraint
    Description

    This status code indicates that the GraphQL request was successfully received by the server. Even if there are errors in the response payload, the request itself was successfully received and acknowledged. The inclusion of errors within the response allows for detailed error reporting while still considering the request as successful. Non-200 status codes typically indicate issues with request transmission or server-side problems preventing the request from reaching the GraphQL server.

  • Name
    401 Unauthorized
    Type
    Constraint
    Description

    If the request lacks valid authentication credentials or the authentication token is invalid, the server may respond with a 401 status code. Clients should handle this code and prompt the user to provide valid credentials.

  • Name
    403 Forbidden
    Type
    Constraint
    Description

    In some cases, even with valid authentication, the server may block access to certain resources or operations. In such cases, the server can respond with a 403 status code to indicate that the request is understood, but access is not allowed. Clients should respect this code and handle it accordingly.

  • Name
    500 Internal Server Error
    Type
    Constraint
    Description

    If there are issues on the server-side that prevent the request from being processed or reaching the GraphQL API, the server may respond with a 500 status code. This typically indicates a problem with the server configuration or infrastructure. Clients should treat this code as a temporary issue and consider retrying the request later.

Error Payload

When an error occurs in a GraphQL API, the response payload includes an array of error objects, each providing specific information about the encountered error. The structure of an error object typically includes the following fields:

  • message: Describes the error message, indicating that the requested field 'username' is not available.
  • locations: Specifies the location where the error occurred. In this case, it is on line 7, column 9.
  • path: Represents the path to the field in the GraphQL query that caused the error. In this example, the error is related to the 'username' field nested under the 'user' field.

In addition to these standard fields, there may be an optional extension field that includes additional error information. This extension section can provide further details about the error, such as the docs_url field, which appears only if the error can be resolved by referring to the documentation.

For example, the extension provided in the given response would be:

Error response

{
	"errors": [
	{
		"message": "The requested field 'username' is not available.",
		"locations": [
		{
			"line": 7,
			"column": 9
		}
		],
		"path": [
		"user",
		"username"
		],
		"extensions": {
			"type": "field_not_found",
			"code": "404",
			"docs_url": "https://api.tbint.app/docs/errors/field_not_found"
		}
	}
	]
}

Successful execution

Operations that execute successfully will return 2xx codes, and, where appropriate, will return the information requested directly in the response body:

  • Name
    200 Ok
    Type
    Constraint
    Description

    successful response.

  • Name
    201 Created
    Type
    Constraint
    Description

    The request will result in a new entity, e.g., import an order

  • Name
    202 Accepted
    Type
    Constraint
    Description

    The request has been accepted for processing

Failed executions

It is also possible that requests fail for any of the following reasons.

  • Name
    400 Bad Request
    Type
    Constraint
    Description

    The server will not process the request.

  • Name
    401 Unauthorized
    Type
    Constraint
    Description

    This error occurs when the access token provided in the API request is either invalid or lacks the necessary permissions to access the API. It's possible that the access token is missing, incorrectly entered, expired, or the necessary permissions or scopes have not been granted.

  • Name
    403 Forbidden
    Type
    Constraint
    Description

    Indicates that the access token is no longer valid or that you don't have permission to use that endpoint.

  • Name
    404 Not Found
    Type
    Constraint
    Description

    The resource is not available. This is often due to querying for something that doesn't exist.

  • Name
    423 Locked
    Type
    Constraint
    Description

    This can happen when the client exceeds the API rate limits

  • Name
    5xx Errors
    Type
    Constraint
    Description

    An internal error occurred