Errors

This page lists common errors and steps you can take as a developer to solve them.

IP blocking

IP’s are blocked dynamically from our platform based on how suspicious it is. An IP will be flagged when a lot of malicious traffic is originating from this IP (e.g. bots, hacking, ddos attacks). Most hosting providers use the same IP for multiple customers, so if malicious actors use the same hosting provider as you, your calls might also be blocked because your requests come in with the same IP as the malicious actors.

Symptoms of your IP being blocked:

Getting a 404 response when trying to fetch your token from https://login.bol.com.
Requests succeed from server A and/or your local machine, but not from server B.

Verify whether your IP is being blocked:

Try performing requests from a different server and/or your local machine. If that succeeds, the server IP is probably being blocked.
Send a mail to the affiliate marketing team so they can check whether your IP is being blocked.

Things you can do to mitigate IP blocking:

Complain to your hosting provider that their IPs are being flagged as being suspicious because a lot of malicious traffic is originating from their IPs.
Switch to a different hosting provider.

Error responses

Below are the most common http error responses.

400 - Bad request

Your request is missing needed information or contains invalid parameters. The response body will contain a violation object containing more concise details. Check the violations table below for an explanation of each individual violation.

Example response body:

{
  "type": "/problems/validation-failed",
  "title": "Your request is missing required fields.",
  "status": 400,
  "violations": [
    {
      "name": "countryCode",
      "reason": "Required query parameter 'country-code' is not present."
    }
  ]
}

401 - Unauthorized

The Authorization request header is not set or the bearer token in the header is invalid. This may be caused by an expired or malformed token. Information on generating a valid token can be found here.

404 - Not Found

The information you are looking for cannot be found on our platform. Not all EANs have a related product on Bol and not all products on Bol will have media or an offer. It may also not be available in the country requested.

Example response body:

{
  "type": "/problems/not-found",
  "title": "No data could be found.",
  "status": 404
}

406 - Not Acceptable

A common cause of this error is setting the Accept header to anything other than json. You can drop this header or set it to application/json. This may also be caused by requesting product information in a language it is not available in.

411 - Length Required

The POST request doesn’t have a body. If this is expected, make sure to execute the request with HTTP version >= 2.0, or add a Content-Length: 0 header to your request.

429 - Too Many Requests

The Marketing Catalog API has rate limiting to avoid overwhelming our systems. You can read more about our rate limiting here.

Example response body:

{
  "type": "/problems/rate-limit-reached",
  "title": "Request rate limit reached",
  "status": 429,
  "detail": "Request limit reached for partner: X"
}

500 - Service Unavailable

The server encountered an unexpected condition that prevented it from fulfilling the request. The request should not be automatically retried. This is an error within the Bol API. If this error persists please contact us via this email.

{
  "type": "/problems/internal-server-error",
  "title": "There was an error fetching the data.",
  "status": 500,
  "detail": "..."
}

503 - Service Unavailable

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. You may retry this request. If this error persists please contact us via this email.

{
  "type": "/problems/unavailable",
  "title": "There was an error fetching the data, please try again later.",
  "status": 503,
  "detail": "..."
}

Violations

When a 400 Bad Request is returned it could contain a list of relevant violations.

Violation

Solutions

{
  "name": "acceptLanguage",
  "reason": "Required header Accept-Language is not present."
}

This means that you have made a request without adding an Accept-Language header. As Bol offers products in multiple languages, we need to know what language you want the response in. Simply include the header with one of the following values: nl, fr, nl-NL, nl-BE or fr-BE.

{
  "name": "acceptLanguage",
  "reason": "Cannot convert en to a AcceptLanguageParam type"
}

This means that you have requested a language that we do not support. Please select one of the following languages: nl, fr, nl-NL, nl-BE or fr-BE.

{
  "name": "X",
  "reason": "Required query parameter X is not present."
}

This means that you are missing a mandatory query parameter named X (e.g. countryCode, search-term). Please check the spec and add the missing field.

{
  "name": "ean",
  "reason": "size must be between 13 and 13"
}

This means that you provided an invalid EAN as query parameter. An EAN should always consist of exactly 13 number.