# Błędy i statusy stron: co się nie udało i czy ponawiać

> Błędy Search API: sześć kodów błędów HTTP (nigdy niepłatne), statusy stron wewnątrz 200 i kiedy ponawiać z backoffem. Bez KYC, płatność kryptowalutą.

- URL: https://llmwebsearch.com/pl/docs/errors/
- Ostatnia aktualizacja: 2026-10-22
- Wydawca: LLMWebSearch (https://llmwebsearch.com)

Istnieją dwa rodzaje problemów. Błąd HTTP oznacza, że całe wywołanie się nie powiodło i nic nie kosztuje. Status strony oznacza, że wyszukiwanie zadziałało, ale jednej strony nie udało się odczytać; znajduje się on wewnątrz normalnej odpowiedzi 200. Agenci powinni obsługiwać oba przypadki, ale inaczej.

**Szybka odpowiedź — Jakie błędy może zwrócić API LLMWebSearch i czy są płatne?**

**LLMWebSearch** ma sześć błędów HTTP: `400 invalid_parameter`, `401 invalid_api_key`, `402 insufficient_credits`, `429 rate_limited`, `502 search_failed` i `504 search_timeout`. Żaden nie jest płatny. Strony, których nie można odczytać, pokazują `content_status` wewnątrz 200. Działające wyszukiwanie kosztuje 1 kredyt, zgodnie z 1,20 USD/1K wyszukiwań na październik 2026. Bez KYC; płatność kryptowalutą.

## Jakie błędy HTTP istnieją?

Treść odpowiedzi to zawsze `{"error": {"code": "…", "message": "…"}}`. Żaden błąd nie zużywa kredytu.

| HTTP | `code` | Przyczyna | Ponawiać? |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | Brakuje wymaganego parametru lub wartość jest poza zakresem | Nie: popraw zapytanie |
| 401 | `invalid_api_key` | Klucz jest nieobecny, błędny lub unieważniony | Nie: sprawdź klucz |
| 402 | `insufficient_credits` | Saldo nie pokrywa tego wywołania | Nie: kup pakiet |
| 429 | `rate_limited` | Więcej wywołań na minutę, niż pozwala konto | Tak, po przerwie |
| 502 | `search_failed` | Wyszukiwania nie udało się ukończyć | Tak, z backoffem |
| 504 | `search_timeout` | Brak wyniku wyszukiwania w ciągu 30 sekund | Tak, z backoffem |

## Czym status strony różni się od błędu?

Status strony opisuje jeden wynik, a nie całe zapytanie. Wyszukiwanie się wykonało, wyniki są, a `credits_used` jest ustawione jak zwykle. Brakuje tylko treści tej jednej strony, a `content_status` mówi dlaczego: `blocked_by_robots`, `blocked_by_site_policy`, `target_refused`, `fetch_failed`, `fetch_timeout` lub `unsupported_content`.

Nie traktuj ich jako błędów, po których należy ponowić całe wyszukiwanie. Wykorzystaj pozostałe wyniki, snippet brakującej strony albo inne źródło. Strona [format odpowiedzi](https://llmwebsearch.com/pl/docs/response/) wyjaśnia każdy status w tabeli.

## Dlaczego nigdy nie ponawiasz wokół odmowy?

Bo odmowa to odpowiedź strony i szanujemy ją. Nasz czytnik respektuje robots.txt: przedstawia się jako LLMWebSearch, przestrzega reguł, które witryna zapisuje dla niego lub dla wszystkich robotów, i pomija treść każdej strony, której nie wolno mu czytać. Witryna, która ustawia Content-Signal: ai-input=no w swoim robots.txt, trzyma treść swoich stron poza treścią Twoich wyników. Gdy strona odrzuca nasz reader kodem 403, 429 lub stroną z wyzwaniem, zgłaszamy to jako `target_refused` ze statusem strony w `target_status`.

Gdy witryna odrzuca nasz czytnik, wynik wraca bez treści i ze statusem witryny: nigdy nie rozwiązujemy CAPTCHA, nie logujemy się na konta ani nie obchodzimy blokady czy paywalla. Nie ponawiamy też z inną tożsamością ani z ukrytą przeglądarką. Twój agent nie powinien zapętlać się na takiej stronie: wynik się nie zmieni, a strona powiedziała nie.

## Kiedy mój kod powinien ponowić próbę?

Tylko przy `429`, `502` i `504`. Poczekaj, a potem spróbuj ponownie, za każdym razem podwajając czas oczekiwania i dodając odrobinę losowości, żeby równolegli pracownicy nie ponawiali w tym samym momencie. Wystarczy od trzech do pięciu prób; potem zgłoś błąd.

Nigdy nie ponawiaj `400`, `401` ani `402`: to samo zapytanie daje tę samą odpowiedź, dopóki czegoś nie zmienisz. Dla stron `fetch_failed` i `fetch_timeout` mogą zadziałać później, przez nowe wyszukiwanie lub wywołanie `/extract`. `target_refused`, `blocked_by_robots` i `blocked_by_site_policy` są ostateczne.

*Python: ponów 429, 502 i 504 z wykładniczym backoffem*

```python
import os
import random
import time

import requests

API = "https://llmwebsearch.com/api/v1/search"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
RETRY_ON = {429, 502, 504}


def search(body, attempts=5):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        resp = requests.post(API, headers=HEADERS, json=body, timeout=60)
        if resp.status_code == 200:
            return resp.json()
        err = resp.json().get("error", {})
        if resp.status_code not in RETRY_ON or attempt == attempts:
            raise RuntimeError(f"{resp.status_code} {err.get('code')}: {err.get('message')}")
        time.sleep(delay + random.uniform(0, delay / 2))
        delay = min(delay * 2, 30)


data = search({"q": "how to rotate api keys without downtime"})
unread = [r["url"] for r in data["results"] if r["content_status"] not in ("ok", "not_requested")]
print("credits:", data["credits_used"], "| pages not read:", unread)

```

## Co zrobić przy 402 insufficient_credits?

Zatrzymaj się i doładuj saldo. Wywołanie nie zostało wykonane i nic nie kosztowało. Aby nie zatrzymywać się w środku długiego zadania, sprawdź najpierw saldo przez `GET https://llmwebsearch.com/api/v1/credits`, które jest darmowe, i porównaj je z liczbą planowanych wyszukiwań. Pamiętaj, że wyszukiwanie z `read` powyżej 3 wymaga 2 kredytów.

Kredyty pochodzą z pakietów kupowanych z Twojego salda kryptowalutowego. Kredyty na wyszukiwanie nie mają daty ważności: to, czego nie wykorzystasz w tym miesiącu, będzie tam jeszcze w przyszłym roku.

## Jak utrzymać się pod rate limitem?

Ogranicz, ile wywołań działa naraz w Twoim kodzie. Każde konto ma limit wywołań na minutę, widoczny w dashboardzie; poproś support, a można go podnieść. Niewielka pula równoległych pracowników, od czterech do ośmiu dla większości agentów, utrzymuje równe tempo bez skoków. Strony [Python](https://llmwebsearch.com/pl/docs/python/) i [Node.js](https://llmwebsearch.com/pl/docs/node/) pokazują taką pulę.

Gdy dostaniesz `429`, zrób pauzę przed następną próbą, zamiast wysyłać ją od razu. Natychmiastowe ponowienie tylko dodaje kolejne odrzucone wywołania.

## Błędy: najczęstsze pytania

### Czy wyszukiwanie, w którym odrzucono każdą stronę, nadal kosztuje kredyt?

Tak, jeśli samo wyszukiwanie się wykonało: nadal dostajesz wyniki w rankingu i snippety. Cena wyszukiwania nie zależy od tego, ile jego stron udało się odczytać.

### Czy 401 może być spowodowany unieważnionym kluczem?

Może. Unieważniony klucz, literówka, brakujący prefiks `Bearer ` lub nagłówek, który do nas nie dotarł, dają `401 invalid_api_key`. Twórz jeden klucz API na agenta, aplikację lub członka zespołu i unieważniaj dowolny z nich z dashboardu, nie ruszając pozostałych.

### Dlaczego strona zwróciła fetch_timeout?

Strony są czytane równolegle, a strona, której odczyt trwa dłużej niż 15 sekund, jest zwracana bez treści, żeby nie blokowała całej odpowiedzi. Wolne strony czasem odpowiadają przy późniejszej próbie.

### Czy mogę zobaczyć swoje nieudane wywołania?

Tak. Historia w panelu wymienia Twoje wywołania z 30 dni, także nieudane, wraz ze statusem i kredytami. Nieudane wywołania pokazują 0 kredytów.

---

LLMWebSearch: LLMWebSearch to web search API dla agentów AI, który zwraca uszeregowane wyniki wraz z treścią najlepszych stron w formacie Markdown, z płatnością kryptowalutą i bez przesyłania dokumentu tożsamości. Kredyty przedpłacone od 1,20 USD/1K wyszukiwań nigdy nie wygasają. Bez KYC — bez dokumentu, bez selfie, bez zaświadczeń. Płatność kryptowalutą.