> ## 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.
# Obsługa błędów
> Obsługuj błędy API Enrow w sposób kontrolowany — formaty odpowiedzi, kody statusu, logika ponawiania i najlepsze praktyki
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](/pl/status-codes).
## Jak wygląda odpowiedź z błędem?
Większość błędów API Enrow zwraca prosty obiekt JSON z jednym polem `message`:
```json theme={null}
{
"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`:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/pl/api-reference/email-finder/find-single) wymaga `fullname` oraz dodatkowo `company_domain` albo `company_name`.
### Dlaczego otrzymuję 401 Unauthorized?
`401` oznacza, że klucz API jest brakujący lub nieprawidłowy:
```json theme={null}
{
"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](/pl/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:
```json theme={null}
{
"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](https://app.enrow.io) lub za pomocą `GET /account/info`. Doładuj środki lub przejdź na wyższy plan na [enrow.io/pricing](https://enrow.io/pricing). Zobacz [Credits & billing](/pl/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ń:
```json theme={null}
{
"message": "Too Many Requests"
}
```
**Rozwiązanie**: Poczekaj i ponów próbę z wykładniczym wycofywaniem (exponential backoff). Zobacz [Rate limits](/pl/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:
```json theme={null}
{
"message": "An unexpected error occurred"
}
```
**Rozwiązanie**: Ponów żądanie z wycofywaniem. Jeśli problem nie ustępuje, skontaktuj się z [api@enrow.io](mailto: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.
```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()
```
## 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.
```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));
}
}
}
```
## 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](/pl/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](/pl/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
Pełna lista kodów statusu HTTP i ich znaczeń.
Poznaj limity żądań dla poszczególnych planów, aby uniknąć błędów 429.
Jak przekazywać klucz API w nagłówku x-api-key.
Zobacz, jak środki są zużywane na każdym endpoincie.