API Error Codes

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Topic

Author:

Kirill Gaiduk

Changed on:

28 May 2025

Overview

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:

Identify Error types
Decode Error Codes
And apply suggested solutions

This supports:

Faster debugging
Better Error handling
And improved integration reliability

The below content covers:

Error Classifications
Known examples
And guidance on when and how to self-resolve vs. escalate

Authors:

Fluent Commerce, Kirill Gaiduk

Changed on:

12 June 2025

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 User For 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., Inventory Feed)	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
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)
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

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}

Language: json

Name: 400 - Bad credentials

Description:

Bad credentials

Endpoint: POST /oauth/token

Missing Name

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 **

Invalid JAR file

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

FAILED Event

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

NO_MATCH Event

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

Missing Retailer

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

Error Code: 401 Examples

Missing Retailer

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 **

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}

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

Invalid Authentication Object

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

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}

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

Error Code: 406 Examples

Invalid Plugin

1Only Verified Bundles Can be Installed

Language: json

Name: 406 - Only Verified Bundles Can be Installed

Description:

Not Acceptable

Endpoint: POST orchestration/rest/v1/plugin/install

Error Code: 500 Examples

Unsupported Operation

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

Internal Server Error

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/ **

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>

Language: json

Name: 500 - Request failed

Description:

Request Failed

Endpoint: POST /orchestration/rest/v1/plugin/bundleStatus

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>

Language: json

Name: 504 - Gateway Time-out

Description:

Gateway timeout

Endpoint: GET /api/v4.1/event

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