API Error Codes
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
GraphQL API Error Codes Overview
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
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
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. |
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:
|
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 |
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 |
|
|
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 |
Related content
REST API Error Codes Overview
Authors:
Holger Lierse, Kirill Gaiduk
Changed on:
26 May 2025
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.
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