> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enrow.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Fehlerbehandlung
> Enrow-API-Fehler souverän behandeln — Antwortformate, Statuscodes, Wiederholungslogik und Best Practices
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](/de/status-codes).
## Wie sieht eine Fehlerantwort aus?
Die meisten Enrow-API-Fehler liefern ein einfaches JSON-Objekt mit einem einzigen Feld `message`:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/de/api-reference/email-finder/find-single) `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:
```json theme={null}
{
"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](/de/authentication) 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:
```json theme={null}
{
"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](https://app.enrow.io) oder über `GET /account/info`. Laden Sie Guthaben auf oder führen Sie ein Upgrade des Tarifs unter [enrow.io/pricing](https://enrow.io/pricing) durch. Unter [Guthaben & Abrechnung](/de/credits-billing) 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:
```json theme={null}
{
"message": "Too Many Requests"
}
```
**Behebung**: Warten Sie und wiederholen Sie die Anfrage mit exponentiellem Backoff. Unter [Ratenbegrenzungen](/de/rate-limits) finden Sie die Limits pro Tarif.
### Warum erhalte ich einen 500 Internal Server Error?
Ein `500` bedeutet, dass auf Enrows Seite etwas fehlgeschlagen ist:
```json theme={null}
{
"message": "An unexpected error occurred"
}
```
**Behebung**: Wiederholen Sie die Anfrage mit Backoff. Falls das Problem weiterhin besteht, wenden Sie sich an [api@enrow.io](mailto: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.
```javascript Node.js theme={null}
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();
}
```
```python Python theme={null}
import requests
import os
def find_email(contact):
response = requests.post(
"https://api.enrow.io/email/find/single",
json=contact,
headers={
"Content-Type": "application/json",
"x-api-key": os.getenv("ENROW_API_KEY")
}
)
if not response.ok:
error = response.json()
message = error.get("message") or error.get("reason")
raise Exception(f"Enrow API error {response.status_code}: {message}")
return 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.
```javascript theme={null}
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](/de/how-webhooks-work)
* **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](/de/rate-limits) 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
Die vollständige Liste der HTTP-Statuscodes und ihrer Bedeutungen.
Verstehen Sie die Anfragelimits pro Tarif, um 429-Fehler zu vermeiden.
So übergeben Sie Ihren API-Schlüssel im x-api-key-Header.
Erfahren Sie, wie Guthaben für jeden Endpunkt verbraucht wird.