---
title: Błędy API
description: Obsługuj ustrukturyzowaną otoczkę błędu, identyfikatory żądań, klasy stanu HTTP, stabilne kody i granice ponawiania.
species: reference
---
# Błędy API

Każde niepowodzenie API używa jednej otoczki. Logikę opieraj na `error.code`, a nie na tekście komunikatu.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter.",
    "param": "sql",
    "doc_url": "https://api.supernova.ai/docs#parameter_missing",
    "request_id": "req_..."
  }
}
```

Nagłówek odpowiedzi `Request-Id` powtarza `request_id`. Podaj go podczas kontaktu z pomocą techniczną. `param` występuje tylko wtedy, gdy można wskazać jedno pole wejściowe.

## Klasy stanu

| Stan | Znaczenie | Ponowienie |
|---|---|---|
| `400` | Nieprawidłowe dane wejściowe lub odrzucona możliwość | Zmień żądanie |
| `401` | Brakujące, nieprawidłowe, wygasłe lub unieważnione dane uwierzytelniające | Odśwież je lub wymień |
| `403` | Uwierzytelniono, ale brakuje zakresu lub roli | Poproś o odpowiedni dostęp |
| `404` | Zasób nie istnieje lub jest ukryty przed tą organizacją | Nie wnioskuj o istnieniu między dzierżawcami |
| `409` | Bieżący stan koliduje z operacją | Odczytaj stan i podejmij decyzję |
| `429` | Limit wywołującego, organizacji lub współbieżności | Przestrzegaj `Retry-After` |
| `500` | Nieoczekiwane niepowodzenie serwera | Ponów ze zwłoką, jeśli żądanie jest idempotentne |
| `503` | Wymagana usługa jest niedostępna | Ponów ze zwłoką |

## Częste kody

| Kod | Znaczenie |
|---|---|
| `invalid_json` | Treść nie jest prawidłowym JSON |
| `parameter_missing` | Brakuje wymaganego pola |
| `invalid_cursor` | Kursor nie pochodzi z odpowiadającej kolekcji |
| `invalid_format` | Żądana reprezentacja nie jest obsługiwana |
| `authentication_required` | Brakuje danych bearer |
| `invalid_token` | Dane uwierzytelniające nie przeszły walidacji |
| `insufficient_scope` | Brakuje zakresu wymaganego przez endpoint |
| `rate_limited` | Przekroczono szybkość żądań |
| `idempotency_key_reused` | Klucz był powiązany z innymi danymi wejściowymi |
| `query_not_found` | Zapytanie jest niedostępne dla tej organizacji |
| `job_not_found` | Zadanie jest niedostępne dla tej organizacji |
| `catalog_not_found` | Schemat lub tabela nie istnieje albo jest ukryta |
| `source_not_found` | Źródło nie istnieje albo jest ukryte |
| `send_not_found` | Wysyłka lub zagnieżdżone uruchomienie nie istnieje albo jest ukryte |

Strony zasobów wymieniają dodatkowe kody przy operacjach, które je zwracają.