Obsługa błędów

API Enrow sygnalizuje problemy za pomocą kodów statusu HTTP oraz treści błędu w formacie JSON. Ten przewodnik wyjaśnia formaty odpowiedzi z błędami, najczęstsze błędy i sposoby ich naprawy, a także jak zbudować niezawodną logikę ponawiania. Pełną listę kodów znajdziesz w sekcji Status codes.

Jak wygląda odpowiedź z błędem?

Większość błędów API Enrow zwraca prosty obiekt JSON z jednym polem message:

{
  "message": "Human-readable error description"
}

Jedynym wyjątkiem jest błąd niewystarczających środków (402) na endpointach pojedynczych (email/phone find single, verify single), który zwraca pole reason obok success:

{
  "reason": "Insufficient credits",
  "success": false
}

Odpowiedzi z błędami nigdy nie zawierają pól error, status ani retry_after. Odczytaj kod statusu HTTP, aby rozgałęzić swoją logikę, oraz pole message (lub reason), aby uzyskać czytelny dla człowieka opis.

Jakie są najczęstsze błędy i jak je naprawić?

Poniższe błędy obejmują zdecydowaną większość nieudanych żądań. Każdy z nich zawiera treść odpowiedzi zwracaną przez API oraz sposób naprawy.

Dlaczego otrzymuję 400 Bad Request?

400 oznacza, że ładunek żądania jest nieprawidłowy lub brakuje wymaganego parametru:

{
  "message": "both company_domain and company_name are absent, input payload needs at least one of them"
}

Rozwiązanie: Sprawdź, czy przekazujesz wszystkie wymagane parametry dla danego endpointu. Na przykład Find Single Email wymaga fullname oraz dodatkowo company_domain albo company_name.

Dlaczego otrzymuję 401 Unauthorized?

401 oznacza, że klucz API jest brakujący lub nieprawidłowy:

{
  "message": "This apikey is not valid"
}

Rozwiązanie: Sprawdź, czy klucz API jest poprawny i wysyłany w nagłówku x-api-key (a nie Authorization). Zobacz Authentication, aby dowiedzieć się, jak przekazywać klucz w każdym żądaniu.

Dlaczego otrzymuję 402 Insufficient Credits?

402 oznacza, że konto nie ma wystarczającej liczby środków, aby wykonać żądanie:

{
  "reason": "Insufficient credits",
  "success": false
}

Na endpointach zbiorczych ten sam 402 jest zwracany w standardowej formie { "message": "..." }. Rozwiązanie: Sprawdź saldo środków w Dashboard lub za pomocą GET /account/info. Doładuj środki lub przejdź na wyższy plan na enrow.io/pricing. Zobacz Credits & billing, aby dowiedzieć się, jak środki są zużywane na poszczególnych endpointach.

Dlaczego otrzymuję 429 Rate Limit Exceeded?

429 oznacza, że w krótkim oknie czasowym wysłano zbyt wiele żądań:

{
  "message": "Too Many Requests"
}

Rozwiązanie: Poczekaj i ponów próbę z wykładniczym wycofywaniem (exponential backoff). Zobacz Rate limits, aby poznać limity dla poszczególnych planów.

Dlaczego otrzymuję 500 Internal Server Error?

500 oznacza, że coś nie powiodło się po stronie Enrow:

{
  "message": "An unexpected error occurred"
}

Rozwiązanie: Ponów żądanie z wycofywaniem. Jeśli problem nie ustępuje, skontaktuj się z api@enrow.io.

Jak obsługiwać błędy w kodzie?

Sprawdź status HTTP przed parsowaniem treści odpowiedzi sukcesu, a następnie zgłoś błąd zawierający kod statusu, aby Twoja logika ponawiania mogła się na nim rozgałęzić. Pole message zawiera opis dla większości błędów, a reason zawiera go dla odpowiedzi 402 z endpointów pojedynczych.

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();
}

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()

Jak ponawiać nieudane żądania?

Ponawiaj tylko te błędy, które warto ponawiać — 429 i 5xx — i stosuj wykładnicze wycofywanie między próbami. Błędy klienta z zakresu 4xx (z wyjątkiem 429) sygnalizują problem z samym żądaniem, więc ich ponawianie nie pomoże.

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));
    }
  }
}

Najlepsze praktyki

Nie ponawiaj błędów 4xx (z wyjątkiem 429) — zamiast tego napraw żądanie
Ponawiaj błędy 429 — zastosuj wykładnicze opóźnienia przed ponowieniem
Ponawiaj błędy 5xx — z wykładniczym wycofywaniem
Używaj webhooków zamiast odpytywania, aby niepotrzebnie nie przekraczać limitów żądań — zobacz How webhooks work
Loguj błędy z kontekstem — uwzględnij endpoint, parametry i znacznik czasu na potrzeby debugowania

FAQ

Jak odróżnić 402 na endpointach pojedynczych od zbiorczych?

Na endpointach pojedynczych (email/phone find single, verify single) 402 zwraca { "reason": "Insufficient credits", "success": false }. Na endpointach zbiorczych ten sam 402 zwraca standardową formę { "message": "..." }. Odczytywanie zarówno message, jak i reason (tak jak robią to przykłady kodu) obsługuje oba przypadki.

Które błędy powinienem ponawiać automatycznie?

Ponawiaj błędy 429 (limit żądań) i 5xx (serwer) z wykładniczym wycofywaniem. Nie ponawiaj innych błędów 4xx, takich jak 400, 401 czy 402 — wskazują one na problem z żądaniem, kluczem API lub saldem środków, którego samo ponawianie nie naprawi.

Czy istnieje nagłówek retry_after informujący, jak długo czekać?

Nie. Odpowiedzi z błędami nigdy nie zawierają pól retry_after, error ani status. Stosuj własne wykładnicze wycofywanie między próbami. Zobacz Rate limits, aby poznać limity obowiązujące w Twoim planie.

Gdzie w odpowiedzi odczytać komunikat błędu?

W przypadku większości błędów opis znajduje się w polu message. W przypadku błędu niewystarczających środków 402 na endpoincie pojedynczym jest on natomiast w polu reason. Zawsze rozgałęziaj swoją logikę na podstawie kodu statusu HTTP, a nie parsując tekst komunikatu.

Kolejne kroki

Status codes

Pełna lista kodów statusu HTTP i ich znaczeń.

Rate limits

Poznaj limity żądań dla poszczególnych planów, aby uniknąć błędów 429.

Authentication

Jak przekazywać klucz API w nagłówku x-api-key.

Credits & billing

Zobacz, jak środki są zużywane na każdym endpoincie.

Pierwsze kroki

Email Finder

Email Verifier

Phone Finder

Konto

Jak wygląda odpowiedź z błędem?

Jakie są najczęstsze błędy i jak je naprawić?

Dlaczego otrzymuję 400 Bad Request?

Dlaczego otrzymuję 401 Unauthorized?

Dlaczego otrzymuję 402 Insufficient Credits?

Dlaczego otrzymuję 429 Rate Limit Exceeded?

Dlaczego otrzymuję 500 Internal Server Error?

Jak obsługiwać błędy w kodzie?

Jak ponawiać nieudane żądania?

Najlepsze praktyki

FAQ

Kolejne kroki

Status codes

Rate limits

Authentication

Credits & billing

​Jak wygląda odpowiedź z błędem?

​Jakie są najczęstsze błędy i jak je naprawić?

​Dlaczego otrzymuję 400 Bad Request?

​Dlaczego otrzymuję 401 Unauthorized?

​Dlaczego otrzymuję 402 Insufficient Credits?

​Dlaczego otrzymuję 429 Rate Limit Exceeded?

​Dlaczego otrzymuję 500 Internal Server Error?

​Jak obsługiwać błędy w kodzie?

​Jak ponawiać nieudane żądania?

​Najlepsze praktyki

​FAQ

​Kolejne kroki

Status codes

Rate limits

Authentication

Credits & billing

Jak wygląda odpowiedź z błędem?

Jakie są najczęstsze błędy i jak je naprawić?

Dlaczego otrzymuję 400 Bad Request?

Dlaczego otrzymuję 401 Unauthorized?

Dlaczego otrzymuję 402 Insufficient Credits?

Dlaczego otrzymuję 429 Rate Limit Exceeded?

Dlaczego otrzymuję 500 Internal Server Error?

Jak obsługiwać błędy w kodzie?

Jak ponawiać nieudane żądania?

Najlepsze praktyki

FAQ

Kolejne kroki