API Error Responses

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Holger Lierse

Changed on:

17 Jan 2024

Overview

GraphQL API Error Codes are summarised in this document.
These include:
- General API Errors
- The error code format explains the format in which the error is shown to the user. It includes:
  - Prefixes
  - Suffixes
  - 4 Digit Code
- Errors are classified into client errors and server errors.
- Current error codes are also classified into client errors and server errors with possible solutions.
Fluent REST API returns specific HTTP error codes which may vary depending on the API endpoint and is explained in this document.

Key points

Fluent API Error Code guide
REST API Error Codes guide

GraphQl API Error Codes

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)

General Errors

Error Code: 401

Description: Invalid Bearer Token

Example:

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

Language: json

Name: 401 - Invalid Bearer Token

Description:

[Warning: empty required content area]

Error code format: <<C/S/T>> <<4 digit code>> <<E/W>>
Examples: C0001E, C00023W, S0001E, S0003W etc

Prefixes:

C Represents client issues. These are usually issues that can be fixed by clients themselves.
S Represents server Issues. Clients can not fix them themselves.
T Represents third party issues.

Suffixes:

E Represents errors.
W Represent warnings.

4 Digit Code:

Represents a unique code for an error. We can classify errors into types. We divide error codes into chunks of 100. Each chunk can be divided into further chunks of 20.

For 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, and 0120 - 0139 represent errors in inputs related to entities. The table below provides further details.

Error Classifications:

4 Digit Sequence	Classification of Error	Description
Client Errors
C0001 - C0099	Platform behaviour	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
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

Current Error Codes

Error Code	Description	Possible Solutions
Client Errors
C0001E	Indicates that a GraphQL query was made with a higher complexity than is allowed by the server.	User is requested to reduce the complexity of the query and try again. Complexity of a query can be reduced by one or all of Reducing the nesting within the query Reducing the requested fields within the query Reducing the number of records requested within the query
C0101E	Indicates that user is querying on dates without passing 'to' or 'from' parameter.	User is requested to pass in at least one of these parameters to get the data they need.
C0100E	Indicates that the user passed in a Non-UTC date value in their operation.	User is requested to pass in a valid UTC format for a date type field.
C0020E	Indicates that the user does not have all the required permissions to execute the query (a view query or mutation query).	User can get all the missing permissions from the error message itself. This list will not contain permission/s of entities in the query that user already has access to. Assign a role to the user that has got more permissions.
C0120E	Validation error on input. Occurs when the user is trying to execute an operation on an entity that could not be found. For example delete mutations. If the entity that the user is trying to delete can not be found, the user will see this error.	User is requested to sanitise their input by validating that they are passing the details for entities that actually exist and that they have access to those entities. 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	Unique constraint violation on field	If a field in the input violates unique constraint.
C0122E	Negative values not allowed for Integer	The integer field does not allow negative values.
C0140E	Missing variables in a query or mutations.	The user should pass in the variables in the query.
C0141E	Char limit exceeded exception	The user should find the char limit from the documentation and update their input and try again
Server Errors
S0001E	Indicates that the entity level permission setting is missing.	Call support to set the setting for the client.

REST API Error Codes

In general the Fluent REST API returns specific HTTP error codes as per the table below. Depending on the API endpoint the error might vary.

Endpoint: POST /oauth/token

Error Code: 400

Description: Bad credentials

Example(s):

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

Language: json

Name: 400 - Bad credentials

Description:

[Warning: empty required content area]

Endpoint: POST /api/v4.1/job **

Error Code: 400

Description: Bad Request

Example(s):

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

Language: json

Name: 400 - Bad Request

Description:

[Warning: empty required content area]

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

Error Code: 400

Description: Bad Request

Example(s):

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

Language: json

Name: 400 - Bad Request

Description:

[Warning: empty required content area]

Endpoint: POST /api/v4.1/event/sync

Error Code: 400

Description: Event failure

Example(s):

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

Language: json

Name: 400 - Event failure

Description:

[Warning: empty required content area]

Endpoint: POST /api/v4.1/event/async or POST /api/v4.1/event/sync

Error Code: 401

Description: Invalid Bearer Token

Example(s):

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

Language: json

Name: 401 - Invalid Bearer Token

Description:

[Warning: empty required content area]

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

Error Code: 401

Description: N/A

Example(s):

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

Language: json

Name: 401 - NA

Description:

[Warning: empty required content area]

Endpoint: POST /api/v4.1/event/sync

Error Code: 400

Description: Event no match (no matching ruleset/entity could be found)

Example(s):

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

Language: json

Name: 400 - Event no match (no matching ruleset/entity could be found)

Description:

[Warning: empty required content area]

Endpoint: PUT /api/v4.1/workflow

Error Code: 400

Description: Bad Request

Example(s):

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

Language: json

Name: 400 - Bad Request

Description:

[Warning: empty required content area]

Endpoint: GET /api/v4.1/event

Error Code: 401

Description: Invalid Bearer Token

Example(s):

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 Bearer Token

Description:

[Warning: empty required content area]

Endpoint: GET/POST /api/v4.1/job **

Error Code: 401

Description: Invalid Bearer Token

Example(s):

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

Language: json

Name: 401 - Invalid Bearer Token

Description:

[Warning: empty required content area]

Endpoint: GET /api/v4.1/workflow **

Error Code: 401

Description: Invalid Bearer Token

Example(s):

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

Language: json

Name: 401 - Invalid Bearer Token

Description:

[Warning: empty required content area]

Endpoint: PUT /api/v4.1/workflow

Error Code: 401

Description: Invalid Bearer Token

Example(s):

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

Language: json

Name: 401 - Invalid Bearer Token

Description:

[Warning: empty required content area]

Endpoint: GET /api/v4.1/workflow

Error Code: 403

Description: Forbidden

Example(s):

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

Language: json

Name: 403 - Forbidden

Description:

[Warning: empty required content area]

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

Error Code: 406

Description: Not Acceptable

Example(s):

1
2
3Only Verified Bundles Can be Installed

Language: json

Name: 406 - Not Acceptable

Description:

[Warning: empty required content area]

Endpoint: n/a

Error Code: 500

Description: Unsupported HTTP operation

Example(s):

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

Language: json

Name: 500 - Unsupported HTTP operation

Description:

[Warning: empty required content area]

Endpoint: GET /api/v4.1/workflow/ **

Error Code: 500

Description: Internal Server Error

Example(s):

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

Language: json

Name: 500 - Internal Server Error

Description:

[Warning: empty required content area]

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

Error Code: 500

Description: Request Failed

Example(s):

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:

[Warning: empty required content area]

Endpoint: GET /api/v4.1/event

Error Code: 504

Description: Gateway timeout

Example(s):

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 timeout

Description:

[Warning: empty required content area]

API Error Responses

Overview

Key points

GraphQl API Error Codes

General Errors

Prefixes:

Suffixes:

4 Digit Code:

Error Classifications:

Current Error Codes

REST API Error Codes

Holger Lierse

Building Blocks

By Type

Helpful Resources

Quick Links