Error Codes

All API errors follow a consistent format. The HTTP status code indicates the category of error, and the response body contains a machine-readable error code and a human-readable message.

Error format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Company not found for KVK number 99999999"
  }
}

Error codes

Code	HTTP Status	Description
`NOT_FOUND`	404	No company found for the given KVK or VAT number.
`INVALID_KVK_NUMBER`	400	The provided KVK number is not a valid 8-digit number.
`INVALID_VAT_NUMBER`	400	The provided VAT number does not match the expected format (e.g., NL + 9 digits + B + 2 digits).
`UNAUTHORIZED`	401	Missing or invalid API key. Ensure you're sending a valid key via the `Authorization` header or `apikey` query parameter.
`RATE_LIMIT_EXCEEDED`	429	You've exceeded the rate limit for your plan. Wait and try again, or upgrade your plan for higher limits.
`QUOTA_EXCEEDED`	429	You've used all your allocated lookups/searches/validations for this month. Upgrade your plan or wait until the next billing cycle.
`UPSTREAM_ERROR`	502	An upstream service (KVK API or VIES) is temporarily unavailable. The request may succeed if retried.
`INTERNAL_ERROR`	500	An unexpected error occurred. If this persists, please contact support.

Handling errors

We recommend checking the HTTP status code first, then parsing the error body for more details:

const res = await fetch("https://api.kvkbase.nl/v1/lookup/12345678", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

if (!res.ok) {
  const { error } = await res.json();

  switch (error.code) {
    case "NOT_FOUND":
      console.log("Company not found");
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Wait and retry
      const retryAfter = res.headers.get("Retry-After");
      break;
    case "QUOTA_EXCEEDED":
      console.log("Monthly quota reached");
      break;
    default:
      console.error("API error:", error.message);
  }
}

Rate limit headers

Every response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your plan
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)