Errors
Error format
Section titled “Error format”Errors with a body use this JSON shape:
{ "refId": "3f1c0d9a8b7e4c2d9f6a5b4c3d2e1f00", "errorCode": "4000", "errorMessage": "Validation error(s)", "errorDetails": { "Limit": { "4004": "Limit must be smaller than or equal to 100" } }}refIdidentifies this error in our logs. Include it when you contact us.errorDetailsis only present on validation errors: parameter name → error code → message.
Status codes
Section titled “Status codes”| Status | Code | Meaning | What to do |
|---|---|---|---|
400 |
4000 |
One or more parameters are invalid; see errorDetails |
Fix the request. Don’t retry unchanged. |
401 |
No API key, or an unknown key | Check the Authorization header (bare key, no Bearer). |
|
403 |
Your key lacks the role for this endpoint | See roles; ask us for the role. | |
404 |
4040 |
Not found, outside your categories, or (on /Prices) no current offers |
Treat as “not available now”. Don’t retry in a loop. |
429 |
Rate limit reached | Back off and retry; see Rate limits. | |
500 |
5000 |
Unexpected error on our side | Retry with backoff. If it persists, contact us with the refId. |
502, 503, 504 |
Temporary infrastructure problem | Retry with backoff. |
Most requests are answered well within a second. Set your client timeout to at least 10 seconds so an occasional slow response doesn’t turn into an error on your side.
Validation error codes
Section titled “Validation error codes”| Code | Meaning |
|---|---|
4001 |
Invalid value, for example an AffiliateId that isn’t registered on your key, or a shop id that isn’t available to you |
4002 |
Required value missing |
4003 |
Too long, or too many items (for example more than 10 Brands) |
4004 |
Out of range, for example Limit above the maximum |
4006 |
Invalid characters, for example letters in Ean |