Błędy

Gdy wywołanie się nie powiedzie, odpowiedź przekazuje dwie informacje: liczbę (code) określającą rodzaj problemu i zdanie (msg) przeznaczone dla człowieka. Ta strona opisuje wszystkie kody, ich znaczenie oraz to, czy ponowienie może pomóc. Jeżeli potrzebujesz szybkiego rozwiązania konkretnego problemu, zacznij od Rozwiązywania problemów.

Wspólna struktura odpowiedzi

Odpowiedzi JSON natywnego API zadań mają tę strukturę — te same cztery pola otaczające każdą odpowiedź. Odpowiedzi zgodności /v1 i SSE odczytuj zgodnie z ich własnymi protokołami:

{ "code": 200, "msg": "success", "data": { }, "request_id": "req_…" }

• code jest kodem biznesowym, nie statusem HTTP. 200 oznacza powodzenie.
• Przy błędzie pole data jest nieobecne (nie ma wartości null) — otrzymujesz code, msg i request_id. Jedyny wyjątek: niektóre błędy biblioteki zasobów dodają data.reason.
• msg jest dla ludzi: jego treść może się zmieniać, podobnie jak język (szczegóły niżej). Nigdy nie uzależniaj logiki od tego tekstu; korzystaj z code.
• request_id jest również zwracane w nagłówku X-Request-Id. Podawaj je przy zgłaszaniu problemu.

Status HTTP również jest ustawiany prawidłowo. Możesz kierować logikę według jednego lub drugiego — ale tylko jednego: konkretne kody są różne (niewystarczające saldo daje code: 40201 i HTTP 402), a ich mieszanie prowadzi w końcu do pominięcia przypadku.

Zalecamy korzystanie z code. 404 mówi tylko „nie znaleziono”; 40201 wskazuje niewystarczające dostępne saldo.

Język komunikatów o błędach

Tekst błędu przeznaczony dla człowieka może być zwracany w wybranym języku. Domyślnie jest to angielski. Wybór obejmuje wyłącznie te trzy miejsca:

• msg we wspólnej strukturze odpowiedzi;
• errorMessage zadania zakończonego niepowodzeniem, zarówno w recordInfo, jak i w callbackach webhooków (z jednym wyjątkiem opisanym niżej);
• error.message w obiektach błędów zgodnych endpointów, niezależnie od formatu OpenAI, Anthropic lub Google Gemini (/v1beta).

Obsługiwane kody języków: en, ja, ko, de, fr, es, pt-BR, ru, it, pl.

Wyjątek: jeżeli sam model poda konkretny powód niepowodzenia — na przykład obraz referencyjny, którego nie mógł odczytać, lub ograniczenie praw autorskich dla wygenerowanego dźwięku — errorMessage zawiera ten powód po angielsku, z usuniętymi szczegółami wewnętrznymi, takimi jak nazwy usług, hosty, adresy URL i identyfikatory żądań. Dzięki temu widzisz rzeczywistą przyczynę. Powody dotyczące stanu konta lub rozliczeń nie są przekazywane dalej; zamiast nich otrzymujesz nasz własny komunikat. Content-Language nadal opisuje msg, a logika zawsze powinna korzystać z errorCode.

Wybór języka

Obowiązuje pierwsza pasująca opcja:

1. Nagłówek żądania Accept-Language, tylko dla tego żądania. Stosujemy standardowe wagi HTTP: wybieramy rozpoznany język o najwyższym q. Warianty regionalne są sprowadzane do języka — de-DE jest traktowane jako de, a pt-PT jako pt-BR. Chiński nie jest dostępny, więc żaden jego znacznik nie pasuje i sprawdzamy kolejną opcję. * oznacza brak preferencji.
2. Ustawienie konta, w sekcji Ustawienia → Język błędów API w konsoli. Obejmuje każde żądanie z kluczem API tego konta bez rozpoznawalnego Accept-Language. Większość serwerowych SDK i curl nie wysyła tego nagłówka domyślnie, dlatego większość integracji korzysta z ustawienia konta. Callbacky webhooków nie mają nagłówka żądania, na którym można oprzeć wybór, więc zawsze korzystają z ustawienia konta.
3. W pozostałych przypadkach — angielski.

Odpowiedzi błędów zawierają nagłówek Content-Language wskazujący język rzeczywiście użyty w komunikacie.

Przykład

Ten sam kod 40201 (niewystarczające saldo) domyślnie wraca po angielsku:

HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

Dodaj nagłówek Accept-Language: ja; pozostała część jest takim samym wywołaniem tworzenia zadania jak w szybkim starcie:

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

msg jest teraz po japońsku; code nadal wynosi 40201:

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

Kody ogólne

503 i 50301 mają ten sam status HTTP, ale są różnymi kodami biznesowymi: 503 dotyczy usługi pomocniczej, a 50301 samego modelu.

Rozróżnianie trzech błędów 401

Trzy różne błędy uwierzytelnienia dają 401 i wymagają różnych poprawek. W każdym przypadku code pozostaje 401; rozróżnia je msg.

Środkowy przypadek jest rozstrzygany bez odczytu bazy danych, dlatego przekazuje informację niedostępną w trzecim: taki ciąg znaków od początku nie mógł zadziałać. Trzeci komunikat jest celowo identyczny dla nieistniejącego, unieważnionego i wygasłego klucza, aby nie pozwalał sprawdzać, które klucze istnieją.

Tutaj pokazujemy te komunikaty po angielsku; msg korzysta z opisanego wyżej wyboru języka, a jego dokładna treść nie jest częścią kontraktu. Kieruj logikę według code, a komunikat traktuj jako tekst do przeczytania, wyświetlenia lub zapisania w logu — nie do porównywania w warunkach.

Konto nie może wywoływać API

W obu przypadkach sam klucz jest prawidłowy; to konto nie może jeszcze korzystać z API.

40310 oznacza niezweryfikowany adres e-mail. Komunikat brzmi Verify your account email to run models and call the API…:

1. Otwórz konsolę. Baner u góry informuje o niezweryfikowanym adresie i pozwala ponownie wysłać wiadomość weryfikacyjną.
2. Otwórz link w wiadomości weryfikacyjnej (sprawdź też spam).
3. Ponów to samo wywołanie. Nie potrzebujesz nowego klucza.

Konsola działa również przy zablokowanym API, więc nadal możesz przeglądać historię.

Zwykłe 403 z komunikatem This account cannot call the API right now oznacza ograniczenie konta. Skontaktuj się z pomocą techniczną i podaj request_id.

Saldo i limity wydatków

Nie warto ponawiać żadnego z tych błędów — saldo i limity nie zmieniają się od ponownego zapytania. Zobacz Limity wydatków.

Uprawnienia

Żaden z tych błędów nie kwalifikuje się do ponowienia.

Kody powodów biblioteki zasobów

Błędy na endpointach biblioteki zasobów (/api/v1/assets…) mogą dodać do zwykłej koperty jedno odczytywalne maszynowo pole, data.reason:

{ "code": 400, "msg": "…", "data": { "reason": "asset_library_locked" }, "request_id": "req_…" }

code, status HTTP, msg i errorCode zadania są takie same z powodem i bez niego, więc dotychczasowa obsługa dalej działa. Powód pojawia się tylko na endpointach biblioteki zasobów, nigdy na innych endpointach natywnych, a warstwa zgodna z OpenAI i inne warstwy zgodności zachowują własne kształty błędów. Lista może się wydłużać: nieznaną wartość traktuj jak brak powodu.

Dostępność modeli

50301 oznacza, że model nie mógł przyjąć zadania w chwili wysyłania: nie znajduje się w ofercie, nie ma aktywnego cennika lub obecnie nie ma dostępnej mocy generowania. Przejściowe problemy z mocą mogą ustąpić przy ograniczonej liczbie ponowień. Niedostępnego modelu lub braku aktywnej ceny nie naprawią kolejne żądania. Odśwież katalog i uzyskaj potwierdzenie użytkownika przed zmianą modelu.

Celowo rozróżniamy 40004 i 50301. 50301 oznacza, że model obecnie nie może przyjąć żadnego zadania — oczekiwanie może pomóc. 40004 oznacza, że model działa, lecz nie obsługuje tego zestawu ustawień, a msg wskazuje ustawienie w nawiasie, na przykład This model cannot serve this parameter combination right now (…). Czekanie nie pomoże; zmiana jednej wartości tak. Żaden z tych błędów nie tworzy zadania ani nie rezerwuje środków.

Kody niepowodzenia zadania

Niepowodzenie po przyjęciu zadania trafia do errorCode w recordInfo. Zbiór jest zamknięty: diagnostyka wewnętrzna nigdy nie trafia do tego pola, więc wartość spoza listy obsłuż jak upstream_failed.

Zadania zakończone niepowodzeniem lub wygaśnięciem zwykle zwalniają całą rezerwację. Niektóre odmowy dotyczące treści są rozliczane według przyjętej wyceny, ale tylko wtedy, gdy strona modelu wyraźnie podaje ten wyjątek. Ostateczną opłatę sprawdzisz w settled i cost. errorMessage jest dla ludzi: opisuje powód, może przytoczyć własny powód modelu po angielsku (zobacz wyżej), a jego brzmienie się zmienia — logika powinna korzystać wyłącznie z errorCode. „Ponowienie” w tej tabeli oznacza wysłanie nowego zadania, które po powodzeniu jest rozliczane ponownie.

Które błędy powodują naliczenie opłaty

Rozliczenie lub zwolnienie środków kończy się automatycznie, także po przerwaniu procesu. Zwykłe niepowodzenia zwalniają całą rezerwację; określone odmowy dotyczące treści, wyraźnie opisane na stronie modelu, są rozliczane według przyjętej wyceny. Sprawdź rozliczenie zadania i saldo, aby potwierdzić wynik — zobacz Rozliczenia.

Kiedy warto ponowić błąd 409

Implementacja ponowień

Stosuj wykładniczo rosnące opóźnienie z losowym rozrzutem, aby wiele nieudanych wywołań nie wracało jednocześnie:

// 409 is operation-specific and must be handled at the call site.
const RETRYABLE = new Set([429, 500, 503, 50301]);

async function callWithRetry(path, init, { attempts = 4 } = {}) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(`https://api.spicyapi.ai/api/v1${path}`, init);

    // A page from the edge network is not our JSON envelope
    if (!res.headers.get('content-type')?.includes('json')) {
      const text = await res.text();
      throw new Error(`HTTP ${res.status}, not JSON: ${text.slice(0, 200)}`);
    }
    const body = await res.json();

    if (body.code === 200) return body.data;
    if (!RETRYABLE.has(body.code)) {
      throw new Error(`${body.code} ${body.msg} (request_id=${body.request_id})`);
    }

    // When the server says how long to wait, trust it
    const retryAfter = Number(res.headers.get('retry-after'));
    const backoff = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 2 ** i * 1000 + Math.random() * 500;

    await new Promise((r) => setTimeout(r, backoff));
  }
  throw new Error('out of retries');
}

import random, time, requests

# 409 is operation-specific and must be handled at the call site.
RETRYABLE = {429, 500, 503, 50301}
BASE = "https://api.spicyapi.ai/api/v1"


def call_with_retry(method: str, path: str, attempts: int = 4, **kwargs) -> dict:
    for i in range(attempts):
        res = requests.request(method, f"{BASE}{path}", **kwargs)

        # A page from the edge network is not our JSON envelope
        try:
            body = res.json()
        except ValueError:
            raise RuntimeError(f"HTTP {res.status_code}, not JSON: {res.text[:200]}")

        if body["code"] == 200:
            return body["data"]
        if body["code"] not in RETRYABLE:
            raise RuntimeError(f'{body["code"]} {body["msg"]} (request_id={body.get("request_id")})')

        # When the server says how long to wait, trust it
        retry_after = res.headers.get("retry-after")
        backoff = float(retry_after) if retry_after else 2**i + random.random() * 0.5
        time.sleep(backoff)

    raise RuntimeError("out of retries")

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"math/rand"
	"net/http"
	"strconv"
	"time"
)

// retryable lists the codes worth another attempt. Anything else returns
// the same answer however many times you ask — and each ask eats your own
// rate limit.
// Whether the generation itself failed is read from recordInfo's state.
var retryable = map[int]bool{429: true, 500: true, 503: true, 50301: true}

type envelope struct {
	Code      int             `json:"code"`
	Msg       string          `json:"msg"`
	Data      json.RawMessage `json:"data"`
	RequestID string          `json:"request_id"`
}

func callWithRetry(newReq func() (*http.Request, error), attempts int, out any) error {
	for i := 0; i < attempts; i++ {
		req, err := newReq()
		if err != nil {
			return err
		}
		res, err := http.DefaultClient.Do(req)
		if err != nil {
			// Transport-level failure: the request may well have arrived.
			// On createTask, send the same Idempotency-Key or this retry
			// turns into a second generation and a second charge.
			time.Sleep(backoff(i, ""))
			continue
		}

		var env envelope
		decErr := json.NewDecoder(res.Body).Decode(&env)
		io.Copy(io.Discard, res.Body)
		res.Body.Close()
		if decErr != nil {
			// Not our JSON envelope, for example a page from the edge network.
			return fmt.Errorf("HTTP %d, response is not JSON: %w", res.StatusCode, decErr)
		}

		if env.Code == 200 {
			return json.Unmarshal(env.Data, out)
		}
		if !retryable[env.Code] {
			return fmt.Errorf("%d %s (request_id=%s)", env.Code, env.Msg, env.RequestID)
		}
		// When the server says how long to wait, trust it
		time.Sleep(backoff(i, res.Header.Get("Retry-After")))
	}
	return fmt.Errorf("out of retries")
}

// backoff trusts Retry-After when present, otherwise backs off
// exponentially with jitter so a batch of failures does not come back
// as one thundering herd.
func backoff(attempt int, retryAfter string) time.Duration {
	if s, err := strconv.Atoi(retryAfter); err == nil && s > 0 {
		return time.Duration(s) * time.Second
	}
	base := time.Duration(1<<attempt) * time.Second
	return base + time.Duration(rand.Intn(500))*time.Millisecond
}

Diagnostyka

Gdy błąd jest niezrozumiały, sprawdź kolejno:

1. request_id — z tą wartością możemy znaleźć dokładne żądanie.
2. code — sprawdź tabele wyżej.
3. Logi w konsoli — wklej ID zadania lub request_id w wyszukiwarkę na stronie Logi, aby otworzyć zadanie: status, koszt, opóźnienie, klucz użyty do wysłania, kod błędu i powód. Parametry żądania i wyniki są pokazywane tylko podczas ich przechowywania, a w zespole wyłącznie rolom uprawnionym do odczytu treści.

msg dla 500 zawsze jest ogólnym komunikatem „usługa chwilowo niedostępna”, bez szczegółów wewnętrznych: struktura wewnętrzna, nazwy komponentów i ślady stosu nigdy nie pojawiają się w odpowiedzi. Możemy je ustalić wyłącznie przez request_id.

Skontaktujesz się z nami, rozpoczynając rozmowę w sekcji Pomoc w konsoli lub pisząc na support@spicyapi.ai. Podaj request_id albo ID zadania, czas (UTC) i code. Nigdy nie wysyłaj klucza API.