Przejdź do głównej treści
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();
}

​
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

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.
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.
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.
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.