Fehler

Bei einem fehlgeschlagenen Aufruf nennt die Antwort zwei Dinge: eine Zahl in code, die die Problemart beschreibt, und einen lesbaren Satz in msg. Diese Seite erklärt jede Zahl und ob ein weiterer Versuch hilft. Für eine schnelle Lösung anhand eines Symptoms beginnen Sie mit Fehlerbehebung.

Die Antwortstruktur

JSON-Antworten der nativen Task-API nutzen dieselben vier umgebenden Felder. Lesen Sie /v1-Kompatibilitätsantworten und SSE nach deren eigenen Protokollen:

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

• code ist ein Geschäftscode, kein HTTP-Status. 200 bedeutet Erfolg.
• Bei Fehler fehlt data; es ist nicht null. Sie erhalten code, msg und request_id. Die eine Ausnahme: Einige Fehler der Asset-Bibliothek fügen data.reason hinzu.
• msg ist für Menschen gedacht. Wortlaut und Sprache können sich ändern; siehe unten. Richten Sie Ihre Programmlogik nie danach aus, sondern nach code.
• request_id steht auch im Header X-Request-Id. Nennen Sie ihn bei Problemmeldungen.

Der HTTP-Status wird ebenfalls korrekt gesetzt. Verwenden Sie einen der beiden Werte, aber nur einen: Bei spezifischen Codes unterscheiden sie sich. Unzureichendes Guthaben ergibt etwa code: 40201 und HTTP 402. Vermischte Behandlung übersieht irgendwann einen Fall.

Wir empfehlen code: 404 sagt nur „nicht gefunden“, 40201 dagegen, dass das verfügbare Guthaben nicht reicht.

Sprache der Fehlermeldungen

Lesbare Fehlertexte können in Ihrer gewählten Sprache erscheinen. Standard ist Englisch. Nur diese drei Stellen folgen der Auswahl:

• msg in der Antwortstruktur;
• errorMessage eines fehlgeschlagenen Tasks in recordInfo und Webhook-Callbacks, mit der unten genannten Ausnahme;
• error.message in Fehlerobjekten kompatibler Endpunkte im OpenAI-, Anthropic- oder Google-Gemini-Format unter /v1beta.

Unterstützte Sprachcodes: en, ja, ko, de, fr, es, pt-BR, ru, it, pl.

Die Ausnahme: Nennt das Modell selbst einen konkreten Fehlergrund, etwa ein nicht lesbares Referenzbild oder eine Urheberrechtsbeschränkung für generiertes Audio, enthält errorMessage diesen Grund auf Englisch. Interne Details wie Servicenamen, Hosts, URLs und Anfrage-IDs werden entfernt, damit Sie den tatsächlichen Fehler verstehen können. Gründe zum Konto- oder Abrechnungszustand werden nie durchgereicht; stattdessen erhalten Sie unsere eigene Meldung. Content-Language beschreibt weiterhin msg; Ihre Programmlogik richtet sich immer nach errorCode.

Sprache auswählen

Die erste zutreffende Ebene gewinnt:

1. Anfrageheader Accept-Language, nur für diese Anfrage. Die übliche HTTP-Gewichtung gilt: Wir verwenden die erkannte Sprache mit dem höchsten q-Wert. Regionale Varianten werden zugeordnet, also de-DE zu de und pt-PT zu pt-BR. Chinesisch wird nicht angeboten; chinesische Tags treffen daher nichts und der nächste Kandidat wird geprüft. * bedeutet keine Präferenz.
2. Kontoeinstellung unter Einstellungen → API-Fehlersprache. Sie gilt für alle Anfragen mit einem API-Key des Kontos ohne erkennbares Accept-Language. Die meisten serverseitigen SDKs und curl senden standardmäßig keinen solchen Header; daher verlassen sich viele Integrationen darauf. Webhook-Callbacks haben keinen Anfrageheader zur Sprachauswahl und folgen immer der Kontoeinstellung.
3. Andernfalls Englisch.

Fehlerantworten enthalten Content-Language mit der tatsächlich verwendeten Meldungssprache.

Beispiel

Derselbe Fehler 40201 für unzureichendes Guthaben erscheint standardmäßig auf Englisch:

HTTP/1.1 402 Payment Required
Content-Language: en

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

Fügen Sie den Header Accept-Language: ja hinzu. Der Rest entspricht der Taskerstellung im Schnellstart:

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 ist nun Japanisch; code bleibt 40201:

HTTP/1.1 402 Payment Required
Content-Language: ja

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

Allgemeine Codes

503 und 50301 teilen einen HTTP-Status, sind aber verschiedene Geschäftscodes: 503 betrifft einen Hilfsdienst, 50301 das Modell selbst.

Die drei 401-Fälle unterscheiden

Drei unterschiedliche Fehler führen bei der Authentifizierung zu 401 und benötigen verschiedene Lösungen. code bleibt jeweils 401; msg erklärt den Unterschied.

Der mittlere Fall wird ohne Datenbankabfrage erkannt. Deshalb kann er etwas sagen, was der dritte nicht kann: Die Zeichenfolge konnte nie funktionieren. Die dritte Meldung ist für nicht vorhandene, widerrufene und abgelaufene Keys bewusst identisch, damit die Antwort nicht zur Prüfung existierender Keys genutzt werden kann.

Hier stehen die Zeichenfolgen auf Englisch; msg folgt der beschriebenen Sprachauswahl. Sein Wortlaut ist keine vertragliche Zusage. Verwenden Sie code für die Logik und die Meldung zum Lesen, Anzeigen oder Protokollieren, nicht zum Zeichenfolgenvergleich.

Konto kann die API nicht aufrufen

In beiden Fällen ist der Key gültig; das Konto kann die API noch nicht aufrufen.

40310 bedeutet unbestätigte E-Mail-Adresse. Die Meldung lautet Verify your account email to run models and call the API…:

1. Öffnen Sie die Konsole. Ein Banner oben weist auf die unbestätigte Adresse hin und kann die Bestätigungsmail erneut senden.
2. Folgen Sie dem Link in der Bestätigungsmail; prüfen Sie auch den Spamordner.
3. Wiederholen Sie denselben Aufruf. Ein neuer Key ist nicht nötig.

Die Konsole funktioniert während der API-Sperre weiter, sodass Sie Ihren Verlauf sehen können.

Ein einfaches 403 mit This account cannot call the API right now bedeutet ein eingeschränktes Konto. Kontaktieren Sie den Support mit request_id.

Guthaben und Limits

Keinen der beiden Fehler behebt bloßes Wiederholen. Guthaben und Limits ändern sich nicht durch erneute Anfrage. Siehe Ausgabenlimits.

Berechtigungen

Keiner dieser Fehler lässt sich durch Wiederholung lösen.

Ursachencodes der Asset-Bibliothek

Fehler an den Endpunkten der Asset-Bibliothek (/api/v1/assets…) können dem üblichen Umschlag ein maschinenlesbares Feld hinzufügen, data.reason:

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

code, HTTP-Status, msg und der Task-errorCode sind mit oder ohne Grund gleich, bestehende Behandlung funktioniert also weiter. Der Grund erscheint nur an den Endpunkten der Asset-Bibliothek, nie an anderen nativen Endpunkten, und die OpenAI-kompatible und andere Kompatibilitätsschichten behalten ihre eigenen Fehlerformen. Die Liste kann wachsen: Behandeln Sie einen unbekannten Wert wie einen fehlenden Grund.

Modellverfügbarkeit

50301 bedeutet, dass das Modell den Task bei Einreichung nicht annehmen konnte: Es ist nicht gelistet, hat keinen aktiven Preis oder derzeit keine Generierungskapazität. Vorübergehende Kapazitätsprobleme können begrenzte Wiederholungen lösen. Ein nicht verfügbares Modell oder fehlender aktiver Preis wird durch wiederholte Anfragen nicht repariert. Aktualisieren Sie den Katalog und holen Sie vor einem Modellwechsel die Bestätigung des Nutzers ein.

40004 und 50301 unterscheiden sich bewusst. Bei 50301 kann das Modell derzeit keinen Task annehmen; Warten kann helfen. Bei 40004 arbeitet das Modell, kann aber diese Kombination nicht bedienen. msg nennt die Einstellung in Klammern, etwa This model cannot serve this parameter combination right now (…). Warten hilft nicht, eine Wertänderung schon. Keiner der beiden Fälle erstellt einen Task oder reserviert Geld.

Fehlercodes eines Tasks

Fehler nach Taskannahme stehen in errorCode von recordInfo. Die Menge ist abgeschlossen: Interne Diagnosen erscheinen hier nie. Behandeln Sie unbekannte Werte wie upstream_failed.

Fehlgeschlagene oder abgelaufene Tasks geben normalerweise die gesamte Reservierung frei. Bestimmte Inhaltsablehnungen werden nur bei ausdrücklich auf der Modellseite genannter Ausnahme zum angenommenen Angebotspreis berechnet. Prüfen Sie settled und cost für die endgültigen Kosten. errorMessage ist für Menschen: Es beschreibt den Grund, kann den modellseitigen Grund auf Englisch wiedergeben, siehe oben, und sein Wortlaut ändert sich. Verwenden Sie ausschließlich errorCode für Ihre Logik. „Erneut versuchen“ bedeutet hier einen neuen Task, der bei Erfolg erneut berechnet wird.

Welche Fehler Geld kosten

Abrechnung oder Freigabe endet automatisch, auch nach Prozessunterbrechung. Gewöhnliche Fehler geben die gesamte Reservierung frei; bestimmte ausdrücklich auf der Modellseite genannte Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet. Prüfen Sie Taskabrechnung und Guthaben für das Ergebnis; siehe Abrechnung.

Wann Wiederholung bei 409 hilft

Wiederholungslogik schreiben

Exponentiell wachsende Wartezeiten mit zufälliger Streuung verhindern, dass viele fehlgeschlagene Anfragen im selben Moment zurückkehren:

// 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
}

Fehlersuche

Wenn ein Fehler unverständlich ist, gehen Sie diese Liste durch:

1. request_id: Damit können wir die genaue Anfrage finden.
2. code: Prüfen Sie die Tabellen oben.
3. Logs in der Konsole: Task-ID oder request_id im Suchfeld unter Logs öffnet den Task mit Status, Kosten, Latenz, verwendendem Key, Fehlercode und Grund. Parameter und Ergebnisse erscheinen nur während ihrer Aufbewahrung; im Team nur für Rollen mit Leseberechtigung für Inhalte.

msg für 500 bleibt eine allgemeine Meldung „Dienst vorübergehend nicht verfügbar“ ohne interne Details. Interne Struktur, Komponentennamen und Stacktraces erscheinen nie in einer Antwort; sie lassen sich nur über request_id verfolgen.

Öffnen Sie unter Support eine Unterhaltung oder schreiben Sie an support@spicyapi.ai. Nennen Sie request_id oder Task-ID, Zeit in UTC und code. Senden Sie niemals einen API-Key.