GraphQL API Error Codes Overview
Essential knowledge
Intended Audience:
Technical User
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. 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:
|
| 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 |
|
| 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 |
|
| 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:
|
| 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) |
|
| 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 |
|
| 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 |
