Skip to main content
Version: Canary 🚧

Errors

Key concepts​

There are several error types in the GraphQL API and you may come across different ones depending on the operations you are trying to perform. This document describes how to add new error types.

Add new error type​

Step 1: Create new error enum​

To create new error codes, add error_codes.py in the target module. Inside this module create an enum with wanted error codes.

from enum import Enum

class ExampleErrorCode(Enum):
    ALREADY_EXISTS = "already_exists"
    GRAPHQL_ERROR = "graphql_error"
    INVALID = "invalid"
    NOT_FOUND = "not_found"
    REQUIRED = "required"
    UNIQUE = "unique"

Step 2: Register newly created error code enum​

To differentiate between built-in Django's error codes and the custom ones, add the error class to the SALEOR_ERROR_CODE_ENUMS list in saleor/graphql/core/utils/error_codes.py.

SALEOR_ERROR_CODE_ENUMS = [
    ExampleErrorCode,
    AccountErrorCode,
    AppErrorCode,
    ...

Step 3: Add error codes to GraphQL enums​

To add error codes to GraphQL enums you should add an entry in saleor/graphql/core/enums.py.

ExampleErrorCode = graphene.Enum.from_enum(error_codes.ExampleErrorCode)

Step 4: Create error class​

To allow usage error code in mutation, add error class in saleor/graphql/core/types/common.py.

class ExampleError(Error):
    code = ExampleErrorCode(description="The error code.", required=True)

Step 5: Assign error codes to mutation​

To use an new error codes in mutation, add error_type_class and error_type_field to Meta inside mutation.

class ExampleMutation(BaseMutation):
    class Meta:
        error_type_class = ExampleError
        error_type_field = "example_errors"

Add custom field to an error type​

Step 1: Add new fields to error class​

To return more information inside error, add a new field to target error class in saleor/graphql/core/types/common.py.

class ExampleError(Error):
    code = ExampleErrorCode(description="The error code.", required=True)
    example_int_value = graphene.Int(description="Example int value.")
    example_string_value =  graphene.String(description="Example string value.")

Step 2: Raise error with custom values​

To return error with custom values, raise an error in target mutation.

error_params = {
    "example_int_value": 1234,
    "example_string_value": "Example error value",
}
raise ValidationError(
    {
        "example_field": ValidationError(
            message="Example message for debugging",
            code=ExampleErrorCode.EXAMPLE,
            params=error_params,
        )
    }
)
Was this page helpful?