Erreurs

En cas d’échec, la réponse donne deux informations : un nombre (code) identifiant le problème et une phrase (msg) pour le lecteur. Cette page liste tous les codes, leur sens et l’utilité d’une nouvelle tentative. Pour corriger rapidement un symptôme, commencez par Dépannage.

L’enveloppe

Les réponses JSON natives de tâches utilisent cette enveloppe avec les mêmes quatre champs. Analysez les réponses compatibles /v1 et les SSE selon leurs propres protocoles :

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

• code est un code métier, pas un statut HTTP. 200 signifie succès.
• En cas d’échec, data est absent, pas null : vous recevez code, msg et request_id. Une seule exception : quelques échecs de la bibliothèque d’assets ajoutent data.reason.
• msg s’adresse au lecteur : son texte et sa langue peuvent changer ; voir ci-dessous. Ne décidez jamais selon ce texte : utilisez code.
• request_id figure aussi dans l’en-tête X-Request-Id. Indiquez-le pour signaler un problème.

Le statut HTTP est également correct. Utilisez l’un ou l’autre, mais un seul : ils divergent pour les codes spécifiques, par exemple code: 40201 avec HTTP 402 pour un solde insuffisant. Les mélanger finit par faire manquer un cas.

Nous recommandons code. 404 dit seulement « introuvable » ; 40201 précise que le solde disponible est insuffisant.

Langue des messages d’erreur

Le texte lisible des erreurs peut être renvoyé dans la langue choisie. L’anglais est la valeur par défaut. Seuls trois emplacements suivent ce choix :

• msg dans l’enveloppe ;
• errorMessage d’une tâche échouée, dans recordInfo et les callbacks webhook, avec une exception ci-dessous ;
• error.message dans les objets d’erreur compatibles, aux formats OpenAI, Anthropic ou Google Gemini (/v1beta).

Codes de langues acceptés : en, ja, ko, de, fr, es, pt-BR, ru, it, pl.

L’exception : lorsque le modèle a fourni un motif précis, par exemple une référence illisible ou une restriction de droits sur l’audio généré, errorMessage reprend ce motif en anglais, après retrait des détails internes comme les noms de services, hôtes, URL et IDs de requêtes. Vous pouvez ainsi comprendre le problème réel. Les motifs concernant l’état du compte ou la facturation ne sont jamais transmis tels quels ; notre propre message les remplace. Content-Language décrit toujours msg, et vos décisions doivent toujours utiliser errorCode.

Choisir la langue

Le premier cas applicable l’emporte :

1. L’en-tête de requête Accept-Language, uniquement pour cette requête. La pondération HTTP standard s’applique : la langue reconnue avec le plus grand q est retenue. Les variantes régionales sont ramenées à leur langue : de-DE vaut de, et pt-PT vaut pt-BR. Le chinois n’étant pas proposé, ses tags ne correspondent à rien et le candidat suivant est essayé. * signifie aucune préférence.
2. Le réglage du compte, dans Paramètres → Langue des erreurs API de la console. Il couvre toutes les requêtes des clés du compte sans Accept-Language reconnu. La plupart des SDK serveur et curl n’envoient pas cet en-tête par défaut ; les intégrations reposent donc généralement sur ce réglage. Les callbacks webhook n’ont pas d’en-tête de requête à consulter et suivent toujours le compte.
3. Sinon, l’anglais.

Les réponses d’erreur portent un en-tête Content-Language indiquant la langue réellement utilisée pour le message.

Exemple

Le même 40201, solde insuffisant, revient en anglais par défaut :

HTTP/1.1 402 Payment Required
Content-Language: en

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

Ajoutez un seul en-tête Accept-Language: ja ; le reste est le même appel de création que dans le démarrage rapide :

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 est désormais en japonais ; code reste 40201 :

HTTP/1.1 402 Payment Required
Content-Language: ja

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

Codes généraux

503 et 50301 ont le même statut HTTP mais des codes métier différents : 503 concerne un service auxiliaire, 50301 le modèle lui-même.

Distinguer les trois 401

Trois erreurs très différentes produisent 401, avec des corrections différentes. code reste 401 dans tous les cas ; msg les distingue.

Le cas intermédiaire est déterminé sans recherche en base, expliquant l’information que le troisième ne donne pas : cette chaîne n’a jamais pu fonctionner. Le troisième message est volontairement identique pour une clé inexistante, révoquée ou expirée, afin d’empêcher l’exploration des clés existantes.

Ces chaînes sont présentées ici en anglais ; msg suit le choix de langue précédent et son texte n’est pas un contrat. Décidez selon code et utilisez le message pour la lecture, l’affichage ou les journaux, jamais pour une comparaison logique.

Le compte ne peut pas appeler l’API

La clé est valide dans ces deux cas ; c’est le compte qui ne peut pas encore appeler l’API.

40310 signifie adresse e-mail non vérifiée. Le message est Verify your account email to run models and call the API… :

1. Ouvrez la console. Une bannière indique que l’adresse n’est pas vérifiée et permet de renvoyer le mail.
2. Ouvrez le lien de vérification ; vérifiez les indésirables.
3. Réessayez le même appel. Aucune nouvelle clé n’est nécessaire.

La console reste utilisable pendant le blocage API, notamment pour l’historique.

Un simple 403 avec This account cannot call the API right now signifie compte restreint. Contactez le support avec request_id.

Solde et plafonds

Réessayer n’aide dans aucun cas : le solde et les plafonds ne changent pas parce que vous redemandez. Voir Plafonds de dépenses.

Permissions

Aucune de ces erreurs ne se résout par nouvelle tentative.

Codes de raison de la bibliothèque d’assets

Les échecs sur les points d’accès de la bibliothèque d’assets (/api/v1/assets…) peuvent ajouter à l’enveloppe habituelle un champ lisible par machine, data.reason :

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

code, le statut HTTP, msg et l’errorCode de la tâche sont identiques avec ou sans raison : votre gestion actuelle continue de fonctionner. La raison n’apparaît que sur les points d’accès de la bibliothèque d’assets, jamais sur les autres points d’accès natifs, et la couche compatible OpenAI et les autres couches de compatibilité gardent leurs propres formes d’erreur. La liste peut s’allonger : traitez une valeur inconnue comme une raison absente.

Disponibilité du modèle

50301 signifie que le modèle n’a pas pu accepter la tâche à l’envoi : il n’est pas proposé, n’a pas de tarif actif ou n’a pas de capacité de génération disponible. Les problèmes temporaires de capacité peuvent se résoudre par tentatives bornées. Un modèle indisponible ou sans tarif actif ne sera pas réparé par des requêtes répétées. Actualisez le catalogue et obtenez la confirmation de l’utilisateur avant de changer de modèle.

40004 et 50301 sont volontairement distincts. 50301 signifie qu’aucune tâche n’est acceptée pour l’instant ; attendre peut aider. 40004 signifie que le modèle fonctionne mais refuse cette combinaison, avec le réglage entre parenthèses dans msg, par exemple This model cannot serve this parameter combination right now (…). Attendre n’aide pas ; modifier une valeur, oui. Aucun des deux ne crée de tâche ni ne réserve de fonds.

Codes d’échec des tâches

Un échec après acceptation arrive dans l’errorCode de recordInfo. L’ensemble est fermé : les diagnostics internes n’apparaissent pas ici ; traitez toute valeur hors liste comme upstream_failed.

Les tâches échouées ou expirées libèrent normalement la réservation entière. Certains refus de contenu sont facturés au devis accepté uniquement si la page du modèle annonce explicitement cette exception. Vérifiez settled et cost pour la facturation finale. errorMessage est destiné au lecteur : il explique le motif, peut reprendre celui du modèle en anglais, voir plus haut, et sa formulation change. Décidez uniquement selon errorCode. Une « nouvelle tentative » signifie ici une nouvelle tâche, facturée à nouveau si elle réussit.

Les erreurs qui coûtent de l’argent

La facturation définitive ou la libération se fait automatiquement, même après une interruption de processus. Les échecs ordinaires libèrent la totalité ; certains refus de contenu annoncés sur la page sont facturés au devis accepté. Vérifiez la facturation de la tâche et le solde ; voir Facturation.

Quand réessayer un 409

Écrire les nouvelles tentatives

Utilisez une temporisation exponentielle avec variation aléatoire, pour éviter que tous les échecs reviennent simultanément :

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

Diagnostic

Pour une erreur incompréhensible, suivez cette liste :

1. request_id : il nous permet de retrouver la requête exacte.
2. code : consultez les tableaux précédents.
3. Journaux de la console : collez l’ID de tâche ou request_id dans la recherche de Journaux pour ouvrir état, coût, latence, clé d’envoi, code d’erreur et motif. Les paramètres et résultats sont affichés uniquement pendant leur conservation et, dans une équipe, aux rôles autorisés à lire le contenu.

Le msg d’un 500 est toujours un « service temporairement indisponible » générique, sans détails internes : aucune structure interne, aucun nom de composant ni aucune trace d’exécution n’apparaît dans une réponse. Seul request_id permet de retrouver ces détails.

Contactez-nous par Support dans la console ou par e-mail à support@spicyapi.ai. Incluez request_id ou l’ID de tâche, l’heure UTC et code. N’envoyez jamais de clé API.