Fehler

Die API meldet jeden Fehler als JSON mit Statuscode, festem Fehlercode und einem lesbaren Text.

Aufbau einer FehlerantwortCopy Anchor Link

Alle öffentlichen Endpunkte antworten bei einem Fehler im selben Format. Ein Beispiel ist eine Anfrage ohne API-Schlüssel:

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

Die API antwortet mit Status 403:

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

• detail.error: der Fehlercode in Großbuchstaben. Werten Sie in Ihrem Code dieses Feld aus.
• detail.message: ein englischer Text zum Lesen, zum Beispiel für Ihr Log. Prüfen Sie diesen Text nicht im Code, denn er kann sich ändern.

Dieses Format gilt nicht für den Data Layer, der mit einem kürzeren Body antwortet.

Manche Fehler enthalten in detail weitere Felder:

Die API meldet Probleme mit dem Schlüssel immer mit 403, nie mit 401. Bei RATE_LIMITED, CONCURRENT_UPDATE, PROVIDER_UNAVAILABLE, PROVIDER_ERROR und INTERNAL_ERROR kann ein neuer Versuch funktionieren, weil der Fehler vorübergehend ist. Bei allen anderen Fehlern ändern Sie erst die Anfrage, das Konto oder den Plan.

Dieses Format gilt für die Endpunkte der API. Bei einem vertippten Pfad außerhalb davon antwortet die API mit {"detail": "Not Found"}. Prüfen Sie deshalb im Code, ob detail ein Objekt ist.

Gemeinsame FehlerCopy Anchor Link

Jeder Endpunkt kann diese Fehler zurückgeben. Die Schlüssel-Codes gelten für den Schlüssel Visitor Intelligence, den Sie auch für /contacts/* und /webhooks nutzen. Enrichment hat eigene Codes.

Visitor IntelligenceCopy Anchor Link

Die acht Besuchs-Endpunkte, zum Beispiel /company-sessions und /company, geben zusätzlich diese Fehler zurück.

Im Free-Plan meldet die API für verborgene Unternehmen keinen Fehler, sondern liefert die Zeile mit blurred: true und nur wenigen Feldern. Mehr dazu unter Pläne.

EnrichmentCopy Anchor Link

Die Endpunkte unter /enrichment/* nutzen den Schlüssel Enrichment.

GET /enrichment/company antwortet auch mit 202 und 404, die keine Fehler sind. 202 heißt, dass das Ergebnis noch nicht fertig ist, und 404 mit "status": "not_found" heißt, dass zu dieser Domain keine Unternehmensdaten vorliegen. Mehr dazu unter Asynchrone Ergebnisse.

AnsprechpartnerCopy Anchor Link

Die Endpunkte unter /contacts/* nutzen den Schlüssel Visitor Intelligence. Wenn ein Aufruf mit einem Fehler endet, bucht Webmetic keine Credits ab. Mehr dazu unter Credits in der API.

WebhooksCopy Anchor Link

Die Endpunkte unter /webhooks nutzen den Schlüssel Visitor Intelligence. Mehr dazu unter Webhooks.

Fehlerbehandlung im CodeCopy Anchor Link

Das Beispiel liest bei einem Fehler den Code aus detail.error und verarbeitet auch einen Text in detail. Bei RATE_LIMITED und CONCURRENT_UPDATE wartet es die Sekunden aus Retry-After und versucht es bis zu dreimal. Wenn der Header fehlt, wartet es nur kurz. Bei allen anderen Fehlern meldet es Status, Code und 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_IHR_API_SCHLUESSEL' },
    });
    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=ihre-website.de',
);

Wenn Ihr Code einen Fehlercode nicht kennt, behandeln Sie ihn wie einen Fehler, den ein neuer Versuch nicht löst.

Nächste SchritteCopy Anchor Link