Zum Hauptinhalt springen
Die Enrow-API signalisiert Probleme über HTTP-Statuscodes und einen JSON-Fehlerkörper. Dieser Leitfaden erklärt die Formate von Fehlerantworten, die häufigsten Fehler und ihre Behebung sowie den Aufbau einer zuverlässigen Wiederholungslogik. Die vollständige Liste der Codes finden Sie unter Statuscodes.

​
Wie sieht eine Fehlerantwort aus?

Die meisten Enrow-API-Fehler liefern ein einfaches JSON-Objekt mit einem einzigen Feld message: 
{
  "message": "Human-readable error description"
}
Die einzige Ausnahme ist ein Fehler wegen unzureichendem Guthaben (402) bei einzelnen Endpunkten (E-Mail/Telefon einzeln finden, einzeln verifizieren), der ein Feld reason neben success zurückgibt: 
{
  "reason": "Insufficient credits",
  "success": false
}
Fehlerantworten enthalten niemals die Felder error, status oder retry_after. Lesen Sie den HTTP-Statuscode aus, um Ihre Logik zu verzweigen, und lesen Sie message (oder reason) für die menschenlesbare Beschreibung.

​
Was sind die häufigsten Fehler und wie behebe ich sie?

Die folgenden Fehler decken die große Mehrheit der fehlgeschlagenen Anfragen ab. Zu jedem Fehler gehören der von der API zurückgegebene Antwortkörper und die Behebung.

​
Warum erhalte ich einen 400 Bad Request?

Ein 400 bedeutet, dass die Anfrage-Nutzlast fehlerhaft ist oder ein erforderlicher Parameter fehlt: 
{
  "message": "both company_domain and company_name are absent, input payload needs at least one of them"
}
Behebung: Stellen Sie sicher, dass Sie alle für den Endpunkt erforderlichen Parameter übergeben. Zum Beispiel benötigt Einzelne E-Mail finden fullname sowie entweder company_domain oder company_name.

​
Warum erhalte ich einen 401 Unauthorized?

Ein 401 bedeutet, dass der API-Schlüssel fehlt oder ungültig ist: 
{
  "message": "This apikey is not valid"
}
Behebung: Überprüfen Sie, ob der API-Schlüssel korrekt ist und im Header x-api-key (nicht Authorization) gesendet wird. Unter Authentifizierung erfahren Sie, wie Sie den Schlüssel bei jeder Anfrage übergeben.

​
Warum erhalte ich einen 402 Insufficient Credits?

Ein 402 bedeutet, dass das Konto nicht über genügend Guthaben verfügt, um die Anfrage auszuführen: 
{
  "reason": "Insufficient credits",
  "success": false
}
Bei Bulk-Endpunkten wird derselbe 402 stattdessen mit dem Standardformat { "message": "..." } zurückgegeben. Behebung: Prüfen Sie das Guthaben im Dashboard oder über GET /account/info. Laden Sie Guthaben auf oder führen Sie ein Upgrade des Tarifs unter enrow.io/pricing durch. Unter Guthaben & Abrechnung erfahren Sie, wie Guthaben pro Endpunkt verbraucht wird.

​
Warum erhalte ich einen 429 Rate Limit Exceeded?

Ein 429 bedeutet, dass in einem kurzen Zeitfenster zu viele Anfragen gesendet wurden: 
{
  "message": "Too Many Requests"
}
Behebung: Warten Sie und wiederholen Sie die Anfrage mit exponentiellem Backoff. Unter Ratenbegrenzungen finden Sie die Limits pro Tarif.

​
Warum erhalte ich einen 500 Internal Server Error?

Ein 500 bedeutet, dass auf Enrows Seite etwas fehlgeschlagen ist: 
{
  "message": "An unexpected error occurred"
}
Behebung: Wiederholen Sie die Anfrage mit Backoff. Falls das Problem weiterhin besteht, wenden Sie sich an api@enrow.io.

​
Wie behandle ich Fehler im Code?

Prüfen Sie den HTTP-Status, bevor Sie den Erfolgskörper parsen, und lösen Sie dann einen Fehler aus, der den Statuscode mitführt, damit Ihre Wiederholungslogik darauf verzweigen kann. Das Feld message enthält die Beschreibung bei den meisten Fehlern, und reason enthält sie bei 402-Antworten von einzelnen Endpunkten. 
async function findEmail(contact) {
  const response = await fetch('https://api.enrow.io/email/find/single', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ENROW_API_KEY
    },
    body: JSON.stringify(contact)
  });

  if (!response.ok) {
    const body = await response.json();
    const error = new Error(`Enrow API error ${response.status}: ${body.message || body.reason}`);
    error.status = response.status;
    throw error;
  }

  return await response.json();
}

​
Wie wiederhole ich fehlgeschlagene Anfragen?

Wiederholen Sie nur die Fehler, bei denen sich eine Wiederholung lohnt — 429 und 5xx — und legen Sie zwischen den Versuchen exponentiell zunehmende Wartezeiten ein. Clientfehler im Bereich 4xx (außer 429) signalisieren ein Problem mit der Anfrage selbst, weshalb eine Wiederholung nicht hilft. 
async function requestWithRetry(fn, maxRetries = 3, baseDelay = 1000) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const isLastAttempt = attempt === maxRetries - 1;

      // Don't retry client errors (except rate limits)
      if (error.status >= 400 && error.status < 500 && error.status !== 429) {
        throw error;
      }

      if (isLastAttempt) throw error;

      const delay = baseDelay * Math.pow(2, attempt);

      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

​
Best Practices

  • Wiederholen Sie keine 4xx-Fehler (außer 429) — beheben Sie stattdessen die Anfrage
  • Wiederholen Sie 429-Fehler — warten Sie mit exponentiell ansteigenden Verzögerungen, bevor Sie es erneut versuchen
  • Wiederholen Sie 5xx-Fehler — mit exponentiellem Backoff
  • Verwenden Sie Webhooks anstelle von Polling, um unnötige Überschreitungen der Ratenbegrenzungen zu vermeiden — siehe Wie Webhooks funktionieren
  • Protokollieren Sie Fehler mit Kontext — fügen Sie zur Fehlersuche den Endpunkt, die Parameter und den Zeitstempel hinzu

​
FAQ

Bei einzelnen Endpunkten (E-Mail/Telefon einzeln finden, einzeln verifizieren) gibt ein 402 { "reason": "Insufficient credits", "success": false } zurück. Bei Bulk-Endpunkten gibt derselbe 402 das Standardformat { "message": "..." } zurück. Wenn Sie sowohl message als auch reason auslesen (wie in den Codebeispielen), sind beide Fälle abgedeckt.
Wiederholen Sie 429-Fehler (Ratenbegrenzung) und 5xx-Fehler (Server) mit exponentiellem Backoff. Wiederholen Sie keine anderen 4xx-Fehler wie 400, 401 oder 402 — sie weisen auf ein Problem mit der Anfrage, dem API-Schlüssel oder dem Guthaben hin, das sich durch bloßes Wiederholen nicht beheben lässt.
Nein. Fehlerantworten enthalten niemals die Felder retry_after, error oder status. Verwenden Sie Ihren eigenen exponentiellen Backoff zwischen den Wiederholungen. Unter Ratenbegrenzungen finden Sie die für Ihren Tarif geltenden Limits.
Bei den meisten Fehlern steht die Beschreibung im Feld message. Bei einem 402 wegen unzureichendem Guthaben an einem einzelnen Endpunkt steht sie stattdessen im Feld reason. Verzweigen Sie Ihre Logik stets anhand des HTTP-Statuscodes, anstatt den Meldungstext zu parsen.

​
Nächste Schritte

Statuscodes

Die vollständige Liste der HTTP-Statuscodes und ihrer Bedeutungen.

Ratenbegrenzungen

Verstehen Sie die Anfragelimits pro Tarif, um 429-Fehler zu vermeiden.

Authentifizierung

So übergeben Sie Ihren API-Schlüssel im x-api-key-Header.

Guthaben & Abrechnung

Erfahren Sie, wie Guthaben für jeden Endpunkt verbraucht wird.