> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/pl/docs/error-codes

# Kody błędów

Poznaj dokumentację API Kody błędów, parametry żądań, pola odpowiedzi, przykłady kodu i obsługę błędów w integracjach DomScan.

### Błędy strukturalne

Każdy błąd API zwraca ten sam kształt JSON: obiekt `error` ze stabilnym `code`, czytelnym `message`, jego `type` i `status` HTTP, informacją, czy jest `retryable`, oraz `request_id` i `docs_url`. Wartość `request_id` zawsze odpowiada nagłówkowi odpowiedzi `X-Request-Id`, dlatego podaj ją, kontaktując się z pomocą techniczną.

```json
{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Nieprawidłowy format domeny",
    "suggestion": "Użyj domeny możliwej do rejestracji, takiej jak example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}
```

### Pola błędu

| Pole | Opis |
| --- | --- |
| `code` | Stabilny, czytelny maszynowo kod błędu. Kody nigdy nie są zmieniane, więc możesz bezpiecznie na nich opierać logikę obsługi. |
| `message` | Czytelne wyjaśnienie błędu. Treść może się zmieniać, dlatego nie analizuj jej w kodzie. |
| `type` | Ogólna kategoria błędu, na przykład `validation_error`, `authentication_error` lub `rate_limit_error`. |
| `status` | Kod statusu HTTP, powtórzony w treści odpowiedzi na potrzeby logów i kolejek. |
| `retryable` | Informacja, czy to samo żądanie może się powieść po ponowieniu go później. |
| `request_id` | Unikalny identyfikator żądania. Odpowiada nagłówkowi `X-Request-Id`. |
| `docs_url` | Link do sekcji dokumentacji, która wyjaśnia ten błąd. |
| `suggestion` | Opcjonalna wskazówka, jak poprawić żądanie. |
| `details` | Opcjonalny kontekst w formie ustrukturyzowanej, na przykład dozwolone metody lub nieprawidłowy parametr. |
| `retry_after` | Opcjonalna liczba sekund, które należy odczekać przed ponowieniem. Wysyłana także jako nagłówek `Retry-After`. |

### Najczęstsze kody błędów

To kody, które większość klientów musi obsługiwać. Niektóre endpointy zwracają bardziej szczegółowe kody, które podlegają tym samym zasadom; pełna lista ze statusem, typem i zachowaniem przy ponawianiu znajduje się w specyfikacji OpenAPI w sekcji `x-domscan-error-codes`. `RATE_LIMIT_EXCEEDED` jest nadal akceptowany jako alias `RATE_LIMITED`.

| Kod | Status HTTP | Typ | Można ponowić | Opis |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | Nie | Brak parametrów lub nieprawidłowe parametry |
| `MISSING_PARAMETER` | 400 | `validation_error` | Nie | Brakuje wymaganego parametru |
| `INVALID_PARAMETER` | 400 | `validation_error` | Nie | Parametr ma nieprawidłową wartość |
| `INVALID_JSON` | 400 | `validation_error` | Nie | Treść żądania nie jest poprawnym JSON-em |
| `INVALID_DOMAIN` | 400 | `validation_error` | Nie | Nieprawidłowy format domeny |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | Nie | TLD nie jest obsługiwane |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | Nie | Ten endpoint przyjmuje domeny możliwe do rejestracji, a nie subdomeny |
| `VALIDATION_ERROR` | 422 | `validation_error` | Nie | Żądanie jest poprawnie zbudowane, ale nie można go przetworzyć |
| `AUTH_REQUIRED` | 401 | `authentication_error` | Nie | Nie podano klucza API ani sesji |
| `INVALID_API_KEY` | 401 | `authentication_error` | Nie | Klucz API jest nieprawidłowy lub został unieważniony |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | Nie | Na Twoim koncie jest za mało kredytów na to żądanie |
| `FORBIDDEN` | 403 | `permission_error` | Nie | Nie masz uprawnień do tej czynności |
| `NOT_FOUND` | 404 | `not_found_error` | Nie | Endpoint lub zasób nie istnieje |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | Nie | Endpoint istnieje, ale nie przyjmuje tej metody HTTP. Nagłówek `Allow` wymienia obsługiwane metody. |
| `CONFLICT` | 409 | `conflict_error` | Nie | Żądanie jest sprzeczne z bieżącym stanem zasobu |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | Nie | Klucz idempotentności został już użyty z innym żądaniem |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | Nie | Ten klucz `Idempotency-Key` został już użyty z innym żądaniem w ciągu ostatnich 24 godzin. Użyj nowego klucza dla nowego żądania. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | Tak | Żądanie z tym kluczem `Idempotency-Key` jest nadal wykonywane. Spróbuj ponownie za chwilę, aby otrzymać zapisaną odpowiedź. |
| `RATE_LIMITED` | 429 | `rate_limit_error` | Tak | Zbyt wiele żądań |
| `INTERNAL` | 500 | `api_error` | Nie | Nieoczekiwany błąd serwera. Jeśli się powtarza, skontaktuj się z pomocą techniczną i podaj identyfikator żądania. |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | Tak | Źródło nadrzędne zwróciło odpowiedź, której nie da się użyć |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | Tak | Źródło nadrzędne jest tymczasowo niedostępne |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | Tak | Usługa jest tymczasowo niedostępna |
| `TIMEOUT` | 504 | `timeout_error` | Tak | Źródło nadrzędne lub rejestr nie odpowiedziało na czas |

### Zasady ponawiania

- Ponawiaj tylko wtedy, gdy `retryable` ma wartość `true`. W przypadku błędów walidacji, uwierzytelniania i uprawnień najpierw popraw żądanie.

- Jeśli występuje `retry_after` lub nagłówek `Retry-After`, odczekaj co najmniej tyle sekund przed kolejną próbą.

- W przeciwnym razie stosuj wykładniczy backoff z jitterem, na przykład 1, 2, 4 i 8 sekund, i przerwij po kilku próbach.

- Przy tworzeniu zadań wsadowych i jobów wysyłaj nagłówek `Idempotency-Key`, aby ponowione żądanie nigdy nie utworzyło duplikatu joba.

- W przypadku innych żądań POST pobierających kredyty nagłówek `Idempotency-Key` sprawia, że ponowienie zwraca zapisaną odpowiedź zamiast ponownie pobierać opłatę.

### Zgodność

Od 10 października 2026 r. każdy endpoint używa tego formatu. Pola, które niektóre endpointy już zwracały, takie jak `credits_remaining`, `purchase_url`, `login_url`, `success` czy `meta`, pozostają w okresie zgodności, więc istniejące integracje nadal działają. W nowym kodzie odczytuj szczegóły błędu z obiektu `error`.
