Which JSON and XML Error Messages can I get using Icecat?

Version: 1.2 (Updated on September 29th, 2026)

This post presents all possible error messages and codes that users may get while sending Icecat JSON or XML product file requests. Firstly, we will sum up all JSON error messages and codes. Secondly, we will explain all XML error messages and codes.

JSON error messages

Every Icecat JSON API error is returned as a single object with four fields:

{"StatusCode": 18, "Code": 404, "Error": "Not Found", "Message": "Not found user by API Token"}

Field	What it is
StatusCode	Icecat’s own error code. This is the value to check in your integration. It is stable and never changes.
Code	The HTTP status code of the response (400, 403 or 404).
Error	The standard HTTP name of that status code.
Message	A human-readable description. ⚠️The text may be returned in your account language, so do not match on it in code. Use StatusCode instead.

The table below lists every StatusCode the JSON API can return.

STATUS CODE	HTTP	ERROR MESSAGE	EXPLANATION	HOW TO FIX
1	400	UserName, lang are mandatory fields	A mandatory parameter is missing.	Add the missing parameter. lang is always required. username (or shopname) is required only when you do not authenticate with an API Access Token (the token identifies your account on its own).
2	404	Lang is unknown	The locale short code is not in the Locale Table.	Use a short code from the Locale Table. The INT locale is not available in JSON. Request a specific locale instead.
3	404	{username} the Icecat user is unknown	The username does not match any Icecat account.	Check the spelling of your Icecat username. If you authenticate with an API Access Token, send it in the api-token header and leave username out (when a token is present, the username is ignored).
4	400	Product identifier(s) is not correct	The product identifiers are not in a valid combination.	Send one of these: Icecat ID on its own; Brand + Product Code; Brand + Product Code + GTIN; or GTIN on its own.
5	403	You have wrong ip address for access	The IP address you send from is not whitelisted.	Add the IP address in My Profile on icecat.biz, or switch to an API Access Token, which works from any IP address.
6	404	Not found for this shopname private key	No private key is configured for your account. This only applies to requests signed with app_key.	This has to be fixed on our side. Please write to us via the contact form.
7	400	Wrong matching shopname with app_key	The app_key and the username belong to different accounts.	Use the app_key that was issued for the same account as the username in your request.
8	404	The requested product is not present in the Icecat database	No data-sheet exists for that identifier.	Check the identifier on the Icecat website first. If the product is genuinely not in the catalogue, write to us via the contact form and your account manager will get in touch to discuss your request.
9	403	Display of content for users with a Full Icecat subscription level will require the use of a server certificate and a dynamic secret phrase. Please, contact your account manager for help with the implementation	Two different causes share this code. Either a free Open Icecat account requested a brand that does not sponsor the free catalogue, or a Full Icecat request was not signed correctly.	Open Icecat account: upgrade to Full Icecat as this content is not part of the free catalogue. Full Icecat account: check that the signature and timestamp are present and current; contact your account manager to set up the server certificate.
10	404	Not found user by application_key	The app_key does not belong to any Icecat user.	Copy the app_key again from My Profile on icecat.biz and make sure no characters were lost.
11	400	Parameter app_key & AppKey are mandatory	The request requires app_key.	Add app_key to the request.
12	403	The requested product is limited for current user vertical, please contact your account manager at Icecat	Your subscription does not cover the vertical this product belongs to.	Request the vertical yourself in the Verticals section of My Profile on icecat.biz. Alternatively, write to us via the contact form and your account manager will get in touch to discuss your subscription.
13	400	For verify your request by app_key you have to send the request by HTTPS protocol.	An app_key request was sent over HTTP.	Send the request over HTTPS.
14	404	Product has brand restrictions or access is limited	The brand has set a publication restriction on this content. It can cover the whole brand or only selected products and languages.	Some restrictions target free accounts only. Upgrading to Full Icecat lifts those. Others apply to every subscription level, and then only an authorised reseller of the brand can access the content. To become one, use the Request authorization button on the product page, or the Add authorization section in My Profile.
15	404	Products datasheet is not yet released	The product’s release date is in the future.	Wait until the release date, or get access earlier as an authorised reseller of the brand — use the Request authorization button on the product page, or the Add authorization section in My Profile.
16	400	Product EAN is not correct	The GTIN/EAN is not valid.	Check that the GTIN is complete and contains digits only.
17	404	Missing information about product	The product exists, but there is no content to return for this request.	Write to us via the contact form. Your account manager will get in touch to discuss your request.
18	404	Not found user by API Token	The token in the api-token header does not belong to any Icecat user.	Make sure you are sending the API Access Token and not the Content Access Token. These are two different tokens and only the first one authenticates API requests. If you are not sure which one you copied, go to My Profile → Access tokens on icecat.biz, revoke the API token, create a new one and use that.
19	400	API Token is not valid UUID	The header value is not a valid UUID.	Check that the header carries the complete token, with no quotation marks, spaces or line breaks around it.
20	400	Query param must be a string	A parameter was sent as a list where a single value is expected.	Send a single value for that parameter.
21	400	Query param must be an array	A parameter was sent as a single value where a list is expected.	Send the parameter as a list.
22	400	Exceed max limit of elements	A list parameter contains too many values.	Split the request into several smaller ones.
23	400	Value for query param cannot be empty	A parameter was sent with an empty value.	Either give the parameter a value or leave it out of the request.
24	400	UserAgent, ip are mandatory fields	The end user’s IP and User-Agent were not passed.	Pass the end user’s IP address and User-Agent — not your server’s.
25	400	AppKey is mandatory field	The AppKey parameter is missing.	Add AppKey to the request.
26	400	User have no required server certificate. Please, contact your account manager for help with the implementation	Your account has no server certificate, and the requested content needs one.	Contact your account manager to set up the server certificate.
30	400	Relations limit is not positive integer	relationsLimit is not a positive whole number.	Send relationsLimit as a positive whole number.
34	400	Exceed max string length	A parameter value is too long.	Shorten the value.

---

XML error messages

Error code (XML)	Error message (XML)	Explanation
200	You are not allowed to have Full Icecat access	An Open Icecat user requested a Full Icecat product data-sheet. Please, request a Full Icecat upgrade.
404	You are not allowed to access a Full Icecat repository with a free Open Icecat account. Please, check the manual or upgrade your account.	The folder at level4 (Full Icecat) is accessed with a free Open Icecat account. For example, the /refs folder.
404	You are assigned to URL Icecat, please request the file using prf.icecat.biz.	A user with an URL subscription is trying to reach an XML repository. Please, reset your subscription via your Profile.
404	Invalid group level.	A file is requested by a user with the wrong (not channel partner type) account type.
404	Please, add this IP address %%ip%% to the \’ Allowed IP addresses\’ setting of your account.	A request is made from a non-whitelisted IP address. Please, add the IP address to your Profile or use Dynamic Tokens.
404	File does not exist.	An incorrect request for a file is made.
200	Language does not exist.	A non-existing locale is provided in lang parameter. Please check the Locale Table.
404 For data.icecat.biz/export/ {repo}/{lang}/{code} | 200 for XML_S3	The requested XML data-sheet is not present in the Icecat database.	A wrong product identifier is used.
404 For data.icecat.biz/export/ {repo}/{lang}/{code} | 200 for XML_S3	Your registration was not confirmed.	An inactive user is making a request. Please, first activate the user account.
401 For data | 200 for XML S3	Login or password is invalid.	The wrong password is used.
404 For data.icecat.biz/export/ {repo}/{lang}/{code} | 200 for XML_S3	You don\’t have access to this language folder.	Your user didn’t subscribe to the requested locale.
200	The requested XML data-sheet is not described in the Icecat database.	The requested product data-sheet is currently undescribed.
200	Product was replaced with .	The requested product data-sheet was mapped to another one.
404	The products datasheet is not public.	User tries to download product with Publish=Limited. To access such product you have to be an authorized reseller of selected Brand.
200	The products datasheet is not yet released.	The Release Date is in the future. Please wait or request to become an authorized reseller of the selected Brand to gain access to such products.
404	Access to this product and language is restricted.	A brand restriction policy is applied. Only authorized resellers can access the brand’s content. Please, request brand permission via the website.
404	This data-sheet is not accessible via Open Icecat repository.	A Full Icecat user is trying to get a Full Icecat product data-sheet from the Open Icecat (Freexml) Repository.
200	This product belongs to a Vertical, you didn\’t subscribe to.	Your Full Icecat account has not susbcribed to this Vertical or main category. Please, request an upgrade.

Gallery & Multimedia

In case you have any questions, please contact your local account manager or contact Icecat directly via the website.

404	Link is not visible	The requested asset – Image or Multimedia – is deactivated by the brand and no longer available.
404	Link is expired	The requested asset – Image or Multimedia – is no longer available because it was active only before a certain ExpiryDate which already passed.
403	Not Authorized	Full Icecat Images and Multimedia are often IP-restricted. Please, add the IP address to your Profile or use Dynamic Tokens.