Fluent Commerce Docs

Understand the Error Code structure: Each code follows the Prefix + 4-digit Code + Suffix format (e.g., C0001E), which instantly reveals the source (Client/Server/Third-party) and type (Error/Warning) of the issue
Quick diagnosis and resolution: Error Codes are grouped by category and purpose, helping developers diagnose and resolve issues faster without deep debugging or guesswork
Self- vs. support-resolvable issues:
- Codes with a C prefix usually point to issues clients can fix on their own
- While S prefixed Codes may require platform support

Tip on API Response

The Fluent GraphQL API will always return a HTTP 200 response (unless there’s a 500 Internal Server Error or a connection timeout)

Error Code Format

Every Error Code adheres to the Prefix + 4-digit Code + Suffix format: <<C/S/T>> <<4 digit code>> <<E/W>> (e.g., `C0001E`, `C0002W`, `S0001E`, `S0003W`).

Prefix

The table lists the Prefixes used in the Error Codes:

Code	Type of Issue	Description
C	Client issues	These are usually issues that can be fixed by clients themselves
S	Server issues	Clients need assistance to resolve the issue
T	Third-party issues	Issues caused during third-party interactions

4 Digit Code

Represents a unique Code for an Error:

Errors are classified into types
Error Codes are divided into chunks of 100
Each chunk can be divided into further chunks of 20

Explanation through an example

Codes from 0100 to 0199 represent erroneous inputs. These are further divided into chunks of 20, each representing an erroneous input based on a criteria. For example:

0100 to 0119 represent errors on inputs related to dates
0120 - 0139 represent errors in inputs related to entities

Find more details in the Error Classification section below.

Suffix

The table lists the Suffixes used in the Error Codes:

Code	Type of Issue
E	Error
W	Warning

Error Classification

Client Errors

4 Digit Sequence	Classification of Error	Description
C0001 - C0099	Platform behavior	Errors that come from platform restrictions but could be fixed by clients
C0001 - C0019	API limit Errors	For example: Indicates that a GraphQL query was made with higher complexity than is allowed by the server
C0020 - C0099	TBC
C0100 - C0199	Input Validations
C0100 - 0119	Date-related	Input validation Errors that have to do with dates and times
C0120 - C0139	Field-related	Input validation Errors that have to do with fields
C0140 - C0159	Request Format-related	Input validation Errors that have to do with the request formats
C0160 - C0179	Custom Validations - TBC
C0180 - C0299	TBC

Server Errors

4 Digit Sequence	Classification of Error	Description
S0001 - S0019	Settings Error	Any Error in Platform Settings. For example, a missing Setting or values of two Settings in conflict with one another
S0020 - S0039	TBC

Error Code Examples

Client Errors

The table lists the details of the Client Error Codes and possible solutions for them.

Error Code	Description	Possible Solutions
C0001E	Indicates that a GraphQL query was made with a higher complexity than is allowed by the server	Simplify the query by reducing: nesting requested fields or number of records
C0003E	Indicates that a Virtual View is still initializing and data is not yet available	Wait until the Virtual View setup completes and status changes to `ACTIVE`
C0011E	User has exceeded the allowable number of GraphQL queries in a given time period	Reduce query frequency
C0020E	User lacks required Permissions to execute the query or mutation	Review the required missing Permissions listed in the Error Message Assign a User Role with the missing Permissions
C0100E	User passed a non-UTC date value	Pass a valid UTC date format
C0101E	User is querying on dates without passing `from` or `to` parameter	Pass at least one of the `from` or `to` parameters
C0102E	User is querying on dates without passing both `from` and `to `parameters	Pass both `from` and `to` parameters
C0103E	Indicates that a query timeframe exceeds allowed max range for the chosen granularity	Reduce timeframe or change granularity
C0120E	Validation error when entity cannot be found during operation (e.g., delete mutation)	Ensure inputs refer to existing Entities accessible by the UserFor example: A User may have access to data for multiple Retailers. Such a User can perform permitted operations on all those Retailers Whereas User who have access to a single Retailer* will only be allowed to perform the permitted operations for data of that Retailer only*
C0121E	Input `ref` violates a unique constraint	Verify the input `ref`
C0122E	Integer field does not allow negative values	Use a positive integer
C0123E	Input field violates a unique constraint	Verify the input field value
C0124E	Indicates that object validation failed, e.g.: Invalid Inventory Feed destination attributes Attempting to assign a parent Inventory Quantity from a different Inventory Position	For Inventory Feeds: Verify that destination attributes are not empty Ensure the following attributes are provided: AWS Account ID AWS S3 Bucket Name Provide only one AWS Account ID and one S3 Bucket Name For Inventory Quantity(ies): Ensure that the parent Inventory Quantity belongs to the same Inventory Position as the child Cross-position parent reassignment is not supported Verify that both parent and child Inventory Quantities reference the same `position_id`
C0125E	User is querying on ranges without passing `from` or `to` parameter	Pass at least one of the `from` or `to` range parameters
CO127E	Indicates that the system could not find a Retailer Entity for the given Type	Ensure that the provided Type is valid and that a corresponding Retailer Entity exists and is accessible
C0128E	Indicates that multiple Products with the same Reference exist within a Product Catalog	Ensure Product Reference uniqueness within a Product Catalog Or use optional `productType` input field to identify the target Product (to be updated with the `updateProduct` mutation)
C0129E	The provided Retailer ID does not match the Retailer associated with the Sourcing Profile	Verify the Retailer ID in the request (`CreateSourcingProfileInput`) Ensure the Sourcing Profile belongs to the same Retailer Use the correct Retailer ID and retry the mutation (`createSourcingProfile`)
C0130E	A circular dependency was detected in the entity relationships	Review the relationships defined in the request Remove self-referencing or cyclic dependencies (e.g., `InventoryQuantity.parent`) Retry the mutation after correcting the relationships
C0131E	Indicates that a `createVirtualPosition` or `updateVirtualPosition` request would result in a Virtual Position with more than the maximum allowed number of Virtual Segments	Reduce the number of segments on the Virtual Position to 100 or fewer, then retry the mutation
C0140E	Missing variables in a query or mutation	Pass the required variables in the query
C0141E	Input field value exceeds max character length	Find the character limit from the documentation Pass a value within this limit
C0160E	Custom validation failed on a specific input field	Review and correct field value per schema custom validations
C0161E	Hash (#) character not allowed in this field input	Remove # character from input
C0162E	The provided timezone is not a valid timezone	Check if the timezone value matches an existing and valid TZ identifier in the Continent/City format
C0180E	The entity does not exist or the caller does not have permission to perform the requested mutation	Verify that the entity identifier is correct Confirm the entity exists Ensure the caller has permission to execute the mutation (e.g., `updateProduct`) Assign the required role or permissions and retry

Server Error Codes

The table lists the details of the Server Error Codes and possible solutions for them.

Error Code	Description	Possible Solutions
S0001E	Indicates that the Entity-level Permission Setting is missing	Raise a support ticket to set the Permission Setting
S0002E	Indicates a general server failure in processing a GraphQL request Indicates that the “Me” query feature has been disabled by account configuration	Try again later or contact support if the issue persists "Me" query can be enabled for the Account by removing the GRAPHQL.DISABLE_GRAPHQL_ME_QUERY Account Setting
S0003E	Indicates that the Account Setting SSO.DETAILS contains invalid JSON values	Update the value using the existing setting API
S0004E	Indicates a failure when trying to create a User in Fluent IDP	Raise a support ticket to investigate
S0005E	Indicates a failure when trying to update a User in Fluent IDP	Raise a support ticket to investigate
S0006E	Indicates that a failure occurred while trying to upsert an Inventory Feed	Review the Inventory Feed configuration or contact support
S0020E	Indicates an unspecified server-side error	Retry the request later Contact support if the issue continues
S0030E	Indicates a failure in setting up the Virtual View	Contact support to investigate Virtual View setup issues
S0040E	Indicates a failure while MeQuery extracting username from a JWT access token	Retry the operation later If not resolved, then raise a support ticket to investigate
S0126E	Indicates that Observability features are turned off	Contact support to enable Observability
S0127E	Indicates that Analytics query feature is turned off	Contact support to enable Analytics

Overview

Fluent REST API returns specific HTTP Error Codes which may vary depending on the API endpoint and are explained in this document.

Key points

Categorization by HTTP Status Code: The errors are organized by standard HTTP status codes (e.g., 400, 401, 403, etc.), which helps developers quickly understand the type of issue
Coverage of Common Scenarios: The examples span a range of typical failure conditions, from authentication issues to plugin errors and timeouts, offering a practical reference for API consumers

REST API Error Codes Examples

The Error Code examples returned by the Fluent REST API are provided below.

Reminder

Depending on the API endpoint the error might vary.

Error Code: 400 Examples

Invalid Credentials

1{
2    "error": "invalid_grant",
3    "error_description": "Bad credentials"
4}

Missing Name

1{
2    "errors": [
3        {
4            "code": "400",
5            "message": "'name' is required"
6        }
7    ]
8}

Invalid JAR file

1{
2    "message": "\"tmpfile\" is not a valid JAR file",
3    "status": 400
4}

FAILED Event

1{
2    "eventId": "74d61610-1f0f-11eb-9c14-f349e6caa9d2",
3    "entityId": "107",
4    "eventStatus": "FAILED",
5    "errorMessage": "Event has Failed"
6}

NO_MATCH Event

1{
2    "eventId": "a0a63630-1f0f-11eb-84d4-45738fb94811",
3    "entityId": "214",
4    "eventStatus": "NO_MATCH"
5}

Missing Retailer

1{
2    "errors": [
3        {
4            "code": "NotNull",
5            "message": "'retailerId' is required"
6        }
7    ]
8}

Error Code: 401 Examples

Missing Retailer

1{
2    "errors": [
3        {
4            "code": "InvalidInput",
5            "message": "Logged in user has no retailer"
6        }
7    ]
8}

Invalid User

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "Invalid user, Authorization header value does not belong to a valid user"
6        }
7    ]
8}

Invalid Authentication Object

1{
2    "error": "unauthorized",
3    "error_description": "An Authentication object was not found in the SecurityContext"
4}

Error Code: 403 Examples

Missing Permissions

1{
2    "errors": [
3        {
4            "code": "403",
5            "message": "User null does not have permission WORKFLOW_VIEW in context PermissionContext(type=RETAILER, id=1)"
6        }
7    ]
8}

Error Code: 406 Examples

Invalid Plugin

1Only Verified Bundles Can be Installed

Error Code: 500 Examples

Unsupported Operation

1{
2    "errors": [
3        {
4            "code": "500",
5            "message": "Request method 'GET' not supported"
6        }
7    ]
8}

Internal Server Error

1{
2    "errors": [
3        {
4            "code": "500",
5            "message": "An unknown error occurred"
6        }
7    ]
8}

Failed Request

1<html>
2 
3<head>
4    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
5    <title>Error 500 Request failed.</title>
6</head>
7 
8<body>
9    <h2>HTTP ERROR 500</h2>
10    <p>Problem accessing /rest/v1/plugin/bundleStatus. Reason:
11        <pre>    Request failed.</pre>
12    </p>
13    <hr><i><small>Powered by Jetty://</small></i>
14    <hr />
15 
16</body>
17 
18</html>

Error Code: 504 Examples

Gateway Timeout

1<html>
2 
3<head>
4    <title>504 Gateway Time-out</title>
5</head>
6 
7<body>
8    <center>
9        <h1>504 Gateway Time-out</h1>
10    </center>
11</body>
12 
13</html>

Overview

This document explains the GraphQL Error Codes used by Fluent Commerce.

Key points

Understand the Error Code structure: Each code follows the Prefix + 4-digit Code + Suffix format (e.g., C0001E), which instantly reveals the source (Client/Server/Third-party) and type (Error/Warning) of the issue
Quick diagnosis and resolution: Error Codes are grouped by category and purpose, helping developers diagnose and resolve issues faster without deep debugging or guesswork
Self- vs. support-resolvable issues:
- Codes with a C prefix usually point to issues clients can fix on their own
- While S prefixed Codes may require platform support

Tip on API Response

The Fluent GraphQL API will always return a HTTP 200 response (unless there’s a 500 Internal Server Error or a connection timeout)

Error Code Format

Every Error Code adheres to the Prefix + 4-digit Code + Suffix format: <<C/S/T>> <<4 digit code>> <<E/W>> (e.g., `C0001E`, `C0002W`, `S0001E`, `S0003W`).

Prefix

The table lists the Prefixes used in the Error Codes:

Code	Type of Issue	Description
C	Client issues	These are usually issues that can be fixed by clients themselves
S	Server issues	Clients need assistance to resolve the issue
T	Third-party issues	Issues caused during third-party interactions

4 Digit Code

Represents a unique Code for an Error:

Errors are classified into types
Error Codes are divided into chunks of 100
Each chunk can be divided into further chunks of 20

Explanation through an example

Codes from 0100 to 0199 represent erroneous inputs. These are further divided into chunks of 20, each representing an erroneous input based on a criteria. For example:

0100 to 0119 represent errors on inputs related to dates
0120 - 0139 represent errors in inputs related to entities

Find more details in the Error Classification section below.

Suffix

The table lists the Suffixes used in the Error Codes:

Code	Type of Issue
E	Error
W	Warning

Error Classification

Client Errors

4 Digit Sequence	Classification of Error	Description
C0001 - C0099	Platform behavior	Errors that come from platform restrictions but could be fixed by clients
C0001 - C0019	API limit Errors	For example: Indicates that a GraphQL query was made with higher complexity than is allowed by the server
C0020 - C0099	TBC
C0100 - C0199	Input Validations
C0100 - 0119	Date-related	Input validation Errors that have to do with dates and times
C0120 - C0139	Field-related	Input validation Errors that have to do with fields
C0140 - C0159	Request Format-related	Input validation Errors that have to do with the request formats
C0160 - C0179	Custom Validations - TBC
C0180 - C0299	TBC

Server Errors

4 Digit Sequence	Classification of Error	Description
S0001 - S0019	Settings Error	Any Error in Platform Settings. For example, a missing Setting or values of two Settings in conflict with one another
S0020 - S0039	TBC

Error Code Examples

Client Errors

The table lists the details of the Client Error Codes and possible solutions for them.

Error Code	Description	Possible Solutions
C0001E	Indicates that a GraphQL query was made with a higher complexity than is allowed by the server	Simplify the query by reducing: nesting requested fields or number of records
C0003E	Indicates that a Virtual View is still initializing and data is not yet available	Wait until the Virtual View setup completes and status changes to `ACTIVE`
C0011E	User has exceeded the allowable number of GraphQL queries in a given time period	Reduce query frequency
C0020E	User lacks required Permissions to execute the query or mutation	Review the required missing Permissions listed in the Error Message Assign a User Role with the missing Permissions
C0100E	User passed a non-UTC date value	Pass a valid UTC date format
C0101E	User is querying on dates without passing `from` or `to` parameter	Pass at least one of the `from` or `to` parameters
C0102E	User is querying on dates without passing both `from` and `to `parameters	Pass both `from` and `to` parameters
C0103E	Indicates that a query timeframe exceeds allowed max range for the chosen granularity	Reduce timeframe or change granularity
C0120E	Validation error when entity cannot be found during operation (e.g., delete mutation)	Ensure inputs refer to existing Entities accessible by the UserFor example: A User may have access to data for multiple Retailers. Such a User can perform permitted operations on all those Retailers Whereas User who have access to a single Retailer* will only be allowed to perform the permitted operations for data of that Retailer only*
C0121E	Input `ref` violates a unique constraint	Verify the input `ref`
C0122E	Integer field does not allow negative values	Use a positive integer
C0123E	Input field violates a unique constraint	Verify the input field value
C0124E	Indicates that object validation failed, e.g.: Invalid Inventory Feed destination attributes Attempting to assign a parent Inventory Quantity from a different Inventory Position	For Inventory Feeds: Verify that destination attributes are not empty Ensure the following attributes are provided: AWS Account ID AWS S3 Bucket Name Provide only one AWS Account ID and one S3 Bucket Name For Inventory Quantity(ies): Ensure that the parent Inventory Quantity belongs to the same Inventory Position as the child Cross-position parent reassignment is not supported Verify that both parent and child Inventory Quantities reference the same `position_id`
C0125E	User is querying on ranges without passing `from` or `to` parameter	Pass at least one of the `from` or `to` range parameters
CO127E	Indicates that the system could not find a Retailer Entity for the given Type	Ensure that the provided Type is valid and that a corresponding Retailer Entity exists and is accessible
C0128E	Indicates that multiple Products with the same Reference exist within a Product Catalog	Ensure Product Reference uniqueness within a Product Catalog Or use optional `productType` input field to identify the target Product (to be updated with the `updateProduct` mutation)
C0129E	The provided Retailer ID does not match the Retailer associated with the Sourcing Profile	Verify the Retailer ID in the request (`CreateSourcingProfileInput`) Ensure the Sourcing Profile belongs to the same Retailer Use the correct Retailer ID and retry the mutation (`createSourcingProfile`)
C0130E	A circular dependency was detected in the entity relationships	Review the relationships defined in the request Remove self-referencing or cyclic dependencies (e.g., `InventoryQuantity.parent`) Retry the mutation after correcting the relationships
C0131E	Indicates that a `createVirtualPosition` or `updateVirtualPosition` request would result in a Virtual Position with more than the maximum allowed number of Virtual Segments	Reduce the number of segments on the Virtual Position to 100 or fewer, then retry the mutation
C0140E	Missing variables in a query or mutation	Pass the required variables in the query
C0141E	Input field value exceeds max character length	Find the character limit from the documentation Pass a value within this limit
C0160E	Custom validation failed on a specific input field	Review and correct field value per schema custom validations
C0161E	Hash (#) character not allowed in this field input	Remove # character from input
C0162E	The provided timezone is not a valid timezone	Check if the timezone value matches an existing and valid TZ identifier in the Continent/City format
C0180E	The entity does not exist or the caller does not have permission to perform the requested mutation	Verify that the entity identifier is correct Confirm the entity exists Ensure the caller has permission to execute the mutation (e.g., `updateProduct`) Assign the required role or permissions and retry

Server Error Codes

The table lists the details of the Server Error Codes and possible solutions for them.

Error Code	Description	Possible Solutions
S0001E	Indicates that the Entity-level Permission Setting is missing	Raise a support ticket to set the Permission Setting
S0002E	Indicates a general server failure in processing a GraphQL request Indicates that the “Me” query feature has been disabled by account configuration	Try again later or contact support if the issue persists "Me" query can be enabled for the Account by removing the GRAPHQL.DISABLE_GRAPHQL_ME_QUERY Account Setting
S0003E	Indicates that the Account Setting SSO.DETAILS contains invalid JSON values	Update the value using the existing setting API
S0004E	Indicates a failure when trying to create a User in Fluent IDP	Raise a support ticket to investigate
S0005E	Indicates a failure when trying to update a User in Fluent IDP	Raise a support ticket to investigate
S0006E	Indicates that a failure occurred while trying to upsert an Inventory Feed	Review the Inventory Feed configuration or contact support
S0020E	Indicates an unspecified server-side error	Retry the request later Contact support if the issue continues
S0030E	Indicates a failure in setting up the Virtual View	Contact support to investigate Virtual View setup issues
S0040E	Indicates a failure while MeQuery extracting username from a JWT access token	Retry the operation later If not resolved, then raise a support ticket to investigate
S0126E	Indicates that Observability features are turned off	Contact support to enable Observability
S0127E	Indicates that Analytics query feature is turned off	Contact support to enable Analytics

Overview

Fluent REST API returns specific HTTP Error Codes which may vary depending on the API endpoint and are explained in this document.

Key points

Categorization by HTTP Status Code: The errors are organized by standard HTTP status codes (e.g., 400, 401, 403, etc.), which helps developers quickly understand the type of issue
Coverage of Common Scenarios: The examples span a range of typical failure conditions, from authentication issues to plugin errors and timeouts, offering a practical reference for API consumers

REST API Error Codes Examples

The Error Code examples returned by the Fluent REST API are provided below.

Reminder

Depending on the API endpoint the error might vary.

Error Code: 400 Examples

Invalid Credentials

1{
2    "error": "invalid_grant",
3    "error_description": "Bad credentials"
4}

Missing Name

1{
2    "errors": [
3        {
4            "code": "400",
5            "message": "'name' is required"
6        }
7    ]
8}

Invalid JAR file

1{
2    "message": "\"tmpfile\" is not a valid JAR file",
3    "status": 400
4}

FAILED Event

1{
2    "eventId": "74d61610-1f0f-11eb-9c14-f349e6caa9d2",
3    "entityId": "107",
4    "eventStatus": "FAILED",
5    "errorMessage": "Event has Failed"
6}

NO_MATCH Event

1{
2    "eventId": "a0a63630-1f0f-11eb-84d4-45738fb94811",
3    "entityId": "214",
4    "eventStatus": "NO_MATCH"
5}

Missing Retailer

1{
2    "errors": [
3        {
4            "code": "NotNull",
5            "message": "'retailerId' is required"
6        }
7    ]
8}

Error Code: 401 Examples

Missing Retailer

1{
2    "errors": [
3        {
4            "code": "InvalidInput",
5            "message": "Logged in user has no retailer"
6        }
7    ]
8}

Invalid User

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "Invalid user, Authorization header value does not belong to a valid user"
6        }
7    ]
8}

Invalid Authentication Object

1{
2    "error": "unauthorized",
3    "error_description": "An Authentication object was not found in the SecurityContext"
4}

Error Code: 403 Examples

Missing Permissions

1{
2    "errors": [
3        {
4            "code": "403",
5            "message": "User null does not have permission WORKFLOW_VIEW in context PermissionContext(type=RETAILER, id=1)"
6        }
7    ]
8}

Error Code: 406 Examples

Invalid Plugin

1Only Verified Bundles Can be Installed

Error Code: 500 Examples

Unsupported Operation

1{
2    "errors": [
3        {
4            "code": "500",
5            "message": "Request method 'GET' not supported"
6        }
7    ]
8}

Internal Server Error

1{
2    "errors": [
3        {
4            "code": "500",
5            "message": "An unknown error occurred"
6        }
7    ]
8}

Failed Request

1<html>
2 
3<head>
4    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
5    <title>Error 500 Request failed.</title>
6</head>
7 
8<body>
9    <h2>HTTP ERROR 500</h2>
10    <p>Problem accessing /rest/v1/plugin/bundleStatus. Reason:
11        <pre>    Request failed.</pre>
12    </p>
13    <hr><i><small>Powered by Jetty://</small></i>
14    <hr />
15 
16</body>
17 
18</html>

Error Code: 504 Examples

Gateway Timeout

1<html>
2 
3<head>
4    <title>504 Gateway Time-out</title>
5</head>
6 
7<body>
8    <center>
9        <h1>504 Gateway Time-out</h1>
10    </center>
11</body>
12 
13</html>

Content in this track:

Fluent Platform Integrations and Connections

APIs Overview

GraphQL API

REST API

GraphQL (GQL) Mutations

API Authentication

API Retries and Exponential Back-offs

Authentication Token Expiry

API Error Codes

Webhooks

Webhooks Frequently Asked Questions

Webhook Receivers

commercetools - Send Payload to External webhook

commercetools - Receive External webhook

Connect SDK - Fluent Webhooks Integration

Build a Webhooks Monitoring Dashboard

End Of Track

API Error Codes

API Error Codes

Overview

GraphQL API Error Codes Overview

Overview

Key points

Error Code Format

Prefix

4 Digit Code

Suffix

Error Classification

Client Errors

Server Errors

Error Code Examples

Client Errors

Server Error Codes

Related content

GraphQL API

REST API Error Codes Overview

REST API Error Codes Overview

Overview

Key points

REST API Error Codes Examples

Error Code: 400 Examples

Invalid Credentials

Missing Name

Invalid JAR file

FAILED Event

NO_MATCH Event

Missing Retailer

Error Code: 401 Examples

Missing Retailer

Invalid User

Invalid Authentication Object

Error Code: 403 Examples

Missing Permissions

Error Code: 406 Examples

Invalid Plugin

Error Code: 500 Examples

Unsupported Operation

Internal Server Error

Failed Request

Error Code: 504 Examples

Gateway Timeout

Related content

REST API

GraphQL API Error Codes Overview

Related content

Introduction to GraphQL

GraphQL API

REST API

Kirill Gaiduk

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links

GraphQL API Error Codes Overview

Overview

Key points

Error Code Format

Prefix