Errors & Troubleshooting

7 min

Where an operation can fail

The HTTP status. For example 401 when the token is missing or expired.

The errors array at the top level of the response. It appears when the query is invalid (unknown field, wrong type, bad syntax). The HTTP status is still 200.

errorCode, errorMessage and errorData in a mutation result. It appears when a business rule fails.

⚠️ WARNING A mutation can return HTTP 200, no top-level errors and still fail. Always check errorCode in the mutation result.

The error fields of a mutation

Field	Description
errorCode	A number. null when the operation succeeds.
errorMessage	The name of the error, split in words.
errorData	Details, for example the list of the keys that were rejected. Empty when the error has no details.

Error codes of the customer mutations

errorCode	Name	When it is returned
1	InvalidCustomer	The customer key (publicKey / customerKey) does not identify an active customer. For marketing actions errorData: list of the rejected customerKey values; otherwise errorData is empty.
2	InvalidCustomerCategory	category does not identify an active customer category. errorData is empty.
3	InvalidStreet	streetKey does not identify an active street. errorData is empty.
4	InvalidEmailFormat	email is not a valid email address. errorData is empty.
5	InvalidCustomerAddress	The address publicKey does not identify an existing active address (CustomerAddressType.active = true). An inactive address cannot be updated or deleted; create a new one with customer.createAddress and use the returned publicKey. errorData is empty.
6	InvalidCompany	companyKey does not identify an active company. errorData is empty.
7	InvalidMarketingAction	marketingActionKey does not identify an active marketing action. errorData: list of the rejected marketingActionKey values.

Error codes of the gift card mutation

organization.createGiftCard can return these codes of the organization mutations:

errorCode	Name	When it is returned
13	GiftCardDuplicateCode	An active, unused gift card with the same code already exists for the organization in an overlapping startOn / expireOn period, or a unique code could not be generated. errorData is empty.
14	InvalidOrganization	organizationKey does not identify an active organization. errorData is empty.
15	InvalidVATCategory	vatCategoryKey does not identify an existing VAT category. errorData is empty.
16	InvalidCurrency	currencyKey does not identify an existing currency. errorData is empty.

For the other organization codes, see the Error Code Glossary in Shared Reference.

Read the catalogue from the API

The errorCodes query returns every code, with its name and its meaning.

Query

query GetErrorCodes {
  errorCodes {
    customer {
      code
      name
      description
    }
    organization {
      code
      name
      description
    }
  }
}

cURL

curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query GetErrorCodes { errorCodes { customer { code name description } organization { code name description } } }"}'

Response

{
  "data": {
    "errorCodes": {
      "customer": [
        {
          "code": 1,
          "name": "InvalidCustomer",
          "description": "The customer key does not identify an active customer."
        }
      ],
      "organization": [
        {
          "code": 13,
          "name": "GiftCardDuplicateCode",
          "description": "An active, unused gift card with the same code already exists."
        }
      ]
    }
  }
}

Common problems

Symptom	Likely cause	Fix
404 when you open the endpoint in a browser	You sent a GET request.	The endpoint only accepts POST.
401 on every request	No token, expired token, or Basic authentication.	Get a token, then send Authorization: Bearer <token>.
401 after it worked for a while	The token expired.	Renew the token and retry.
HTTP 200 with a top-level errors array	Invalid query: unknown field, wrong type, bad syntax.	Check field names and types in the GraphQL Playground, then fix the query.
A mutation returns errorCode	A business rule failed.	Read errorMessage and errorData. Fix the input and retry.
items: []	No record matches the filter.	Not an error. Check the filters. Lists return active records by default.
A customer you expect isn't listed	The list returns active customers only.	Check that the customer is active.
Missing records in a list	Only the first page was read.	Page through the results until hasNextPage is false.
orders is rejected	There are no order keys and no period.	Send order keys, or a period of at most 1 year.
Points balance differs from the application	The balance was calculated on your side.	Read loyalty.points.balance.
The gift card code is refused	A card with the same code exists in an overlapping period, or the code is invalid.	Leave code out, or use another code of at most 8 letters and digits.

Correct call order: get a token, send it in the header, then send the query or mutation as POST.