Docs
Author:
Kirill Gaiduk
Changed on:
28 May 2025
This article explains how to interpret and act on GraphQL and REST API Error Codes to resolve issues faster.
Implementing partners will learn how to:
This supports:
The below content covers:
Authors:
Fluent Commerce, Kirill Gaiduk
Changed on:
12 June 2025
This document explains the GraphQL Error Codes used by Fluent Commerce.
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`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 |
Represents a unique Code for an Error:
The table lists the Suffixes used in the Error Codes:
Code | Type of Issue |
E | Error |
W | Warning |
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 |
4 Digit Sequence | Classification of Error | Description |
S0001 - S0019 | Settings Error | Any Error in Platform Settings. |
S0020 - S0039 | TBC |
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:
|
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 |
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 |
|
C0100E | User passed a non-UTC date value | Pass a valid UTC date format |
C0101E | User is querying on dates without passing | Pass at least one of the |
C0102E | User is querying on dates without passing both | Pass both |
C0103E | Indicates that a query timeframe exceeds allowed max range for the chosen granularity |
|
C0120E | Validation error when entity cannot be found during operation (e.g., delete mutation) | Ensure inputs refer to existing Entities accessible by the User For example:
|
C0121E | Input | Verify the input |
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., Inventory Feed) |
|
C0125E | User is querying on ranges without passing | Pass at least one of the |
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 |
|
C0140E | Missing variables in a query or mutation | Pass the required variables in the query |
C0141E | Input field value exceeds max character length |
|
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 |
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 |
|
|
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 |
|
S0020E | Indicates an unspecified server-side error |
|
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 |
|
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 |
Authors:
Holger Lierse, Kirill Gaiduk
Changed on:
26 May 2025
Fluent REST API returns specific HTTP Error Codes which may vary depending on the API endpoint and are explained in this document.
The Error Code examples returned by the Fluent REST API are provided below.
1{
2 "error": "invalid_grant",
3 "error_description": "Bad credentials"
4}Language: json
Name: 400 - Bad credentials
Description:
Bad credentials
Endpoint: POST /oauth/token
1{
2 "errors": [
3 {
4 "code": "400",
5 "message": "'name' is required"
6 }
7 ]
8}Language: json
Name: 400 - 'name' is required
Description:
Bad Request
Endpoint: POST /api/v4.1/job **
1{
2 "message": "\"tmpfile\" is not a valid JAR file",
3 "status": 400
4}Language: json
Name: 400 - \"tmpfile\" is not a valid JAR file
Description:
Bad Request
Endpoint: POST /orchestration/rest/v1/plugin/upload
1{
2 "eventId": "74d61610-1f0f-11eb-9c14-f349e6caa9d2",
3 "entityId": "107",
4 "eventStatus": "FAILED",
5 "errorMessage": "Event has Failed"
6}Language: json
Name: 400 - Event has Failed
Description:
Event failure
Endpoint: POST /api/v4.1/event/sync
1{
2 "eventId": "a0a63630-1f0f-11eb-84d4-45738fb94811",
3 "entityId": "214",
4 "eventStatus": "NO_MATCH"
5}Language: json
Name: 400 - Event no match
Description:
Event no match (no matching Ruleset / Entity could be found)
Endpoint: POST /api/v4.1/event/sync
1{
2 "errors": [
3 {
4 "code": "NotNull",
5 "message": "'retailerId' is required"
6 }
7 ]
8}Language: json
Name: 400 - 'retailerId' is required
Description:
Bad Request
Endpoint: PUT /api/v4.1/workflow
1{
2 "errors": [
3 {
4 "code": "InvalidInput",
5 "message": "Logged in user has no retailer"
6 }
7 ]
8}Language: json
Name: 401 - Logged in user has no retailer
Description:
Invalid Bearer Token
Endpoints:
- POST /api/v4.1/event/async
- POST /api/v4.1/event/sync
- POST /orchestration/rest/v1/plugin/ **
- GET/POST /api/v4.1/job **
- GET /api/v4.1/workflow **
1{
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8}Language: json
Name: 401 - Invalid user, Authorization header value does not belong to a valid user
Description:
Invalid Bearer Token
Endpoint: GET /api/v4.1/event
1{
2 "error": "unauthorized",
3 "error_description": "An Authentication object was not found in the SecurityContext"
4}Language: json
Name: 401 - An Authentication object was not found in the SecurityContext
Description:
Invalid Bearer Token
Endpoint: PUT /api/v4.1/workflow
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}Language: json
Name: 403 - User null does not have permission WORKFLOW_VIEW in context PermissionContext(type=RETAILER, id=1)
Description:
Forbidden
Endpoint: GET /api/v4.1/workflow
1Only Verified Bundles Can be InstalledLanguage: json
Name: 406 - Only Verified Bundles Can be Installed
Description:
Not Acceptable
Endpoint: POST orchestration/rest/v1/plugin/install
1{
2 "errors": [
3 {
4 "code": "500",
5 "message": "Request method 'GET' not supported"
6 }
7 ]
8}Language: json
Name: 500 - Request method 'GET' not supported
Description:
Unsupported HTTP operation
Endpoint: n/a
1{
2 "errors": [
3 {
4 "code": "500",
5 "message": "An unknown error occurred"
6 }
7 ]
8}Language: json
Name: 500 - An unknown error occurred
Description:
Internal Server Error
Endpoint: GET /api/v4.1/workflow/ **
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>Language: json
Name: 500 - Request failed
Description:
Request Failed
Endpoint: POST /orchestration/rest/v1/plugin/bundleStatus
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>Language: json
Name: 504 - Gateway Time-out
Description:
Gateway timeout
Endpoint: GET /api/v4.1/event
Copyright © 2025 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.
