Błędy
Kody statusu HTTP i struktura odpowiedzi z błędem.
API sygnalizuje błędy standardowymi kodami statusu HTTP i zwraca treść JSON o stałej strukturze:
{
"message": "Project not found",
"status": 404,
"timestamp": "2026-07-25T10:32:04.512Z",
"path": "/v1/projects/8f14e45f-.../calls"
}message jest zrozumiały dla człowieka — zapisuj go w logach zamiast własnych komunikatów.
Kody statusu
| Kod | Co oznacza | Co zrobić |
|---|---|---|
400 | Niepoprawne żądanie — błędny JSON, nieobsługiwany format nagrania, zbyt duży plik, pusty plik | Popraw żądanie; ponowienie nie pomoże |
401 | Brakujący, niepoprawny, wygasły, dezaktywowany lub usunięty klucz — albo endpoint niedostępny dla kluczy | Sprawdź klucz oraz to, czy endpoint należy do publicznego API |
402 | Organizacja wykorzystała limit audio | Dokup godziny lub zmień plan; potem ponów |
403 | Uwierzytelniono, ale brak uprawnień do tej operacji | Nie ponawiaj |
404 | Zasób nie istnieje albo organizacja klucza go nie widzi | Sprawdź identyfikator i projekt |
409 | Zduplikowane przesłanie — to nagranie jest już w projekcie; albo ponowne zakończenie tego samego bezpośredniego przesłania (bez existingJobId) | Kontynuuj z existingJobId, jeśli jest w odpowiedzi |
429 | Przekroczono limit żądań | Odczekaj i ogranicz częstotliwość żądań; uwzględnij Retry-After |
5xx | Coś poszło nie tak po naszej stronie | Ponów z wykładniczo rosnącym odstępem |
Dwa przypadki wymagające szczególnej obsługi
404 zamiast 403 dla danych innych organizacji. Żądanie projektu, do którego klucz nie ma dostępu,
zwraca 404, a nie 403 — nie da się w ten sposób sprawdzać, czy dany identyfikator istnieje. Jeśli dostajesz
nieoczekiwane 404, sprawdź, czy identyfikator należy do organizacji klucza.
409 przy przesyłaniu to zwykle dobra wiadomość. Oznacza, że nagranie już jest w systemie, a opłata nie została
naliczona dwukrotnie. Zobacz zduplikowane przesłania.
Ponawianie
Ponawiaj 429 i 5xx z wykładniczo rosnącym odstępem. Nie ponawiaj 400, 401, 403 ani 404 —
wynik się nie zmieni (wyjątkiem jest 404 z wywołania upload-complete przed zakończeniem PUT: ponowienie
powiedzie się, gdy przesyłanie pliku się zakończy). 402 można ponowić, ale dopiero po dokupieniu godzin lub
zmianie planu.
Przesłania są deduplikowane na podstawie skrótu zawartości, więc ponowienie przesłania po przekroczeniu limitu czasu połączenia nie utworzy zduplikowanej rozmowy ani nie naliczy drugiej opłaty.