Errors

What an error looks like

{
  "error": {
    "code": "invalid_parameter",
    "message": "A parameter in your request has a value this address does not accept, or is sent twice.",
    "parameter": "limit"
  }
}

• code: what went wrong, as a fixed code. Codes never change once published.
• message: the same in one sentence.
• parameter: the parameter that is the problem, for invalid_parameter and unknown_parameter. Not there otherwise.

Errors are free

A request that ends in an error never counts towards the requests in your plan, whether the error is on your side or on Belscope’s side. Only successful answers count.

Where an error says to contact us: info@belscope.be.

Errors on your side

400invalid_enterprise_numberThe enterprise number in your request is not valid.

{
  "error": {
    "code": "invalid_enterprise_number",
    "message": "The enterprise number in your request is not valid."
  }
}

What to doCheck the number you sent. It must be 10 digits, for example 0123.456.749. Dots, spaces and BE in front are fine. One wrong digit, for example a typo, makes the number invalid.

400key_in_urlYour API key was sent in the address of the request.

{
  "error": {
    "code": "key_in_url",
    "message": "Your API key was sent in the address of the request."
  }
}

What to doSend the key only in the Authorization header. Anyone who sees the address can now see your key: revoke it in your account on belscope.be and create a new one.

400unknown_parameterYour request has a parameter this address does not accept.

{
  "error": {
    "code": "unknown_parameter",
    "message": "Your request has a parameter this address does not accept."
  }
}

What to doThe error names the parameter (parameter). Remove it: the pages of these docs show exactly what each address accepts.

400invalid_parameterA parameter in your request has a value this address does not accept, or is sent twice.

{
  "error": {
    "code": "invalid_parameter",
    "message": "A parameter in your request has a value this address does not accept, or is sent twice."
  }
}

What to doThe error names the parameter (parameter). Check its value against the parameters on the page of this address, for example a number where a number is expected, a code written as in the lists, or a search without any filter.

401invalid_keyYour API key is missing, wrong or no longer valid.

{
  "error": {
    "code": "invalid_key",
    "message": "Your API key is missing, wrong or no longer valid."
  }
}

What to doSend your API key with every request, in the header Authorization: Bearer YOUR_KEY. Check that you copied the whole key, without spaces. A revoked key, or an account that is not active (yet), also gives this error.

404company_not_foundNo company has this number.

{
  "error": {
    "code": "company_not_found",
    "message": "No company has this number."
  }
}

What to doCheck the number for a typo. If it is correct, the company has stopped or never existed. Sending it again gives the same answer.

404not_foundThere is nothing at this address.

{
  "error": {
    "code": "not_found",
    "message": "There is nothing at this address."
  }
}

What to doCheck the address of your request for a typo, against the pages of these docs.

405method_not_allowedThis address only answers GET requests.

{
  "error": {
    "code": "method_not_allowed",
    "message": "This address only answers GET requests."
  }
}

What to doSend the request as GET.

429rate_limitedYou sent too many requests in a short time.

{
  "error": {
    "code": "rate_limited",
    "message": "You sent too many requests in a short time."
  }
}

What to doWait a few seconds, then send the request again. Spread your requests over time instead of sending them all at once.

429quota_exceededYou have used all requests in your plan for this month.

{
  "error": {
    "code": "quota_exceeded",
    "message": "You have used all requests in your plan for this month."
  }
}

What to doContact us if you need more requests.

Errors on Belscope’s side

500internal_errorThe API is up, but something broke while handling this request.

{
  "error": {
    "code": "internal_error",
    "message": "The API is up, but something broke while handling this request."
  }
}

What to doIf it keeps failing for this request, contact us.

503unavailableThe API is down for everyone right now.

{
  "error": {
    "code": "unavailable",
    "message": "The API is down for everyone right now."
  }
}

What to doWait a few minutes, then send the request again.