Errors

The API reports every error as JSON with a status code, a fixed error code, and a readable text.

Error response formatCopy Anchor Link

All public endpoints answer an error in the same format. One example is a request without an API key:

curl "https://hub.webmetic.de/company-sessions?domain=your-website.com"

The API answers with status 403:

{
  "detail": {
    "error": "API_KEY_MISSING",
    "message": "Send your API key in the Authorization header."
  }
}

• detail.error: the error code in capitals. Check this field in your code.
• detail.message: an English text for people, for example for your log. Don't check this text in code, because it can change.

This format doesn't apply to the Data Layer, which answers with a shorter body.

Some errors contain more fields in detail:

The API always reports problems with the key as 403, never as 401. For RATE_LIMITED, CONCURRENT_UPDATE, PROVIDER_UNAVAILABLE, PROVIDER_ERROR, and INTERNAL_ERROR, a new attempt can work because the error is temporary. For all other errors, change the request, the account, or the plan first.

This format applies to the API endpoints. For a mistyped path outside them, the API answers {"detail": "Not Found"}. So check in your code whether detail is an object.

Common errorsCopy Anchor Link

Any endpoint can return these errors. The key codes apply to the Visitor Intelligence key, which you also use for /contacts/* and /webhooks. Enrichment has its own codes.

Visitor IntelligenceCopy Anchor Link

The eight visit endpoints, for example /company-sessions and /company, also return these errors.

On the Free plan, the API reports no error for hidden companies but returns the row with blurred: true and only a few fields. For details, see Plans.

EnrichmentCopy Anchor Link

The endpoints under /enrichment/* use the Enrichment key.

GET /enrichment/company also answers with 202 and 404, which are not errors. 202 means the result isn't ready yet, and 404 with "status": "not_found" means there is no company data for this domain. For details, see Asynchronous results.

ContactsCopy Anchor Link

The endpoints under /contacts/* use the Visitor Intelligence key. If a call ends with an error, Webmetic deducts no credits. For details, see Credits in the API.

WebhooksCopy Anchor Link

The endpoints under /webhooks use the Visitor Intelligence key. For details, see Webhooks.

Error handling in codeCopy Anchor Link

The example reads the code from detail.error when an error comes back, and it also handles a text in detail. For RATE_LIMITED and CONCURRENT_UPDATE, it waits the seconds in Retry-After and tries up to three times. If the header is missing, it waits only briefly. It reports all other errors with status, code, and text.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const RETRY = ['RATE_LIMITED', 'CONCURRENT_UPDATE'];

async function callWebmetic(url, attempts = 3) {
  for (let i = 1; i <= attempts; i++) {
    const res = await fetch(url, {
      headers: { Authorization: 'wmtc_YOUR_API_KEY' },
    });
    if (res.ok) return res.json();

    const { detail } = await res.json();
    // Paths outside the API answer {"detail": "Not Found"}
    const known = detail !== null && typeof detail === 'object';
    const error = known ? detail.error : `HTTP_${res.status}`;
    const message = known ? detail.message : String(detail);
    // Temporary errors: wait and try again
    if (RETRY.includes(error) && i < attempts) {
      const retryAfter = Number(res.headers.get('Retry-After'));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : 1000 * i); // Retry-After first, else the backoff
      continue;
    }
    throw new Error(`${res.status} ${error}: ${message}`);
  }
}

const data = await callWebmetic(
  'https://hub.webmetic.de/company-sessions?domain=your-website.com',
);

If your code doesn't know an error code, treat it as an error that a new attempt won't fix.

Next stepsCopy Anchor Link