--- title: Errors & Troubleshooting slug: devdocs/errors-and-troubleshooting docTags: createdAt: 2026-10-16T12:03:52.217Z --- ## Where an operation can fail 1. **The HTTP status.** For example 401 when the token is missing or expired. 2. **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. 3. **`errorCode`, `errorMessage` and `errorData` in a mutation result.** It appears when a business rule fails. :::BlockQuote ⚠️ **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** ```graphql query GetErrorCodes { errorCodes { customer { code name description } organization { code name description } } } ``` **cURL** ```bash curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{"query": "query GetErrorCodes { errorCodes { customer { code name description } organization { code name description } } }"}' ``` **Response** ```json { "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 `. | | 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`.