Dépannage et reprise

Chaque section ci-dessous part de ce que vous voyez, explique la cause habituelle et vous dit quoi faire. Pour la signification complète de chaque numéro d’erreur, consultez Erreurs ; cette page-ci répond à la question « et maintenant ? ».

Trouver votre problème

Conserver les bons éléments

Avant de modifier quoi que ce soit, notez ce qui s’est passé. Toutes les étapes ci-dessous en deviennent plus rapides, et c’est exactement ce dont l’assistance a besoin :

• L’heure, en UTC si possible.
• Le point de terminaison appelé, par exemple POST /api/v1/jobs/createTask.
• Le statut HTTP et le code du corps de la réponse.
• Le request_id : il figure dans le corps de la réponse et dans l’en-tête de réponse X-Request-Id.
• L’identifiant de la tâche, si vous en avez reçu un. Il commence par job_ et apparaît aussi sur la page Journal de la console.

Distinguez trois situations, car elles n’appellent pas les mêmes gestes : l’API a explicitement refusé la requête (vous avez reçu une erreur JSON — rien n’a été créé ni facturé), vous n’avez reçu aucune réponse (un dépassement de délai ou une connexion coupée — la tâche existe peut-être ; voir plus bas), ou la tâche a été acceptée puis a échoué (vous avez un identifiant de tâche avec state: "failed").

Si une réponse n’est pas du JSON — par exemple une page HTML ou du texte brut —, elle provient de notre réseau périphérique, avant d’atteindre l’API. Notez le statut HTTP et les premières lignes du corps. Une page 403 de ce type signifie en général que la requête vient d’une région que nous ne pouvons pas servir ; réessayer n’y changera rien.

Ne placez jamais de clés API, de mots de passe, de prompts complets ni de fichiers d’origine dans des journaux généraux ou dans une demande d’assistance.

Paiement effectué, solde inchangé

• Carte : le solde ne change qu’une fois que la confirmation du prestataire de paiement nous parvient, en général en quelques secondes. Actualisez Facturation et vérifiez Demandes de recharge.
• Crypto : le solde est crédité une fois la transaction confirmée par le réseau, en général en quelques minutes. Un paiement inférieur au montant affiché, ou effectué après l’expiration de la page de paiement, n’est pas crédité automatiquement.
• Virement manuel : ouvrez la demande dans Demandes de recharge et saisissez la référence bancaire ou le hash de la transaction. Nous le vérifions à la main, en général en quelques heures.

La liste complète des cas se trouve dans Préparer votre compte → Problèmes fréquents. Toujours rien ? Ouvrez une conversation dans Assistance (sujet Facturation) en indiquant l’identifiant de la demande et, pour la crypto, le hash de la transaction. N’envoyez jamais de numéro de carte ni de mot de passe.

Chaque appel renvoie 401 ou 403

Commencez par un appel gratuit qui ne modifie rien : la lecture de votre solde.

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

La première ligne doit afficher sk-spicy-. Si elle n’affiche rien, la clé n’est pas chargée dans ce terminal : définissez-la de nouveau (voir Préparer votre compte). Lisez ensuite le msg de la réponse :

Aucune de ces erreurs ne s’arrange en réessayant.

Solde, limites et assistance

• 40201 — le solde disponible ne couvre pas le prix estimé de la tâche. Ajoutez des fonds (voir Préparer votre compte), puis renvoyez la même requête avec la même Idempotency-Key. Une dotation promotionnelle ne paie que les modèles qu’elle couvre.
• 40202 — une limite de dépense a été atteinte ; msg précise laquelle. Un plafond de clé (This key has reached its …) se relève dans Clés API → Modifier, ou se remet à zéro tout seul (le quotidien à 00:00 UTC, le mensuel le 1er du mois, le cumulé jamais). Une limite d’équipe (Workspace … budget has been reached) se relève sur la page Équipe, par un propriétaire, un administrateur ou un gestionnaire du budget. Le plafond de la plateforme (Platform quota for today is exhausted…) ne peut pas être relevé ; réessayez après 00:00 UTC. Voir Facturation (plafonds de dépense).
• 429 — trop de requêtes. Attendez le nombre de secondes indiqué dans Retry-After et ralentissez ; remplacer les boucles d’interrogation serrées par des webhooks est ce qui aide le plus. Si le message est Too many pending uploads…, attendre ne sert à rien : terminez les téléversements que vous avez déjà commencés. Voir Limites de débit.

Contacter l’assistance : ouvrez une conversation dans Assistance depuis la console, ou écrivez à support@spicyapi.ai. Joignez les éléments listés plus haut : l’heure, le point de terminaison, le code, le request_id ou l’identifiant de tâche, ce que vous attendiez et ce qui s’est produit, ainsi que la structure de votre requête sans ses valeurs privées. N’envoyez jamais de clé API.

Modèle absent ou indisponible

• Le modèle n’est pas dans votre liste, ou vous recevez 404 : appelez GET /api/v1/models avec votre clé API et choisissez un modèle dont enabled et available valent tous deux true, en recopiant son identifiant à l’identique. La page d’un modèle sur le site ne prouve pas que votre clé peut l’appeler en ce moment. Voir Modèles et points de terminaison.
• 50301 — le modèle ne peut pas accepter de tâches pour le moment. Réessayez quelques fois en allongeant les pauses, puis arrêtez-vous : répéter les requêtes ne rendra pas disponible un modèle indisponible. Actualisez le catalogue, et demandez à la personne qui paie avant de passer à un autre modèle.
• 40004 — le modèle fonctionne, mais pas avec cette combinaison de réglages. Le msg nomme le réglage entre parenthèses. Changez cette valeur (par exemple une résolution ou un format d’image) au lieu de réessayer.
• 40301 — le modèle existe, mais cette clé n’a pas le droit de l’utiliser ; modifiez les modèles autorisés de la clé.

Entrée invalide ou conflit de devis

• 400 — comparez votre input avec l’inputSchema actuel du modèle dans le catalogue : noms de champs, types, valeurs autorisées et exigences conditionnelles. Retirez les champs que le modèle ne liste pas. Vérifiez de nouveau après avoir changé de modèle, car chaque modèle a son propre schéma.
• 40003 — un fichier téléversé ne correspond pas à ce que vous aviez déclaré en demandant son URL de téléversement. Demandez une nouvelle URL de téléversement avec le bon contentType et la bonne taille, puis téléversez de nouveau.
• 413 — le corps de la requête est trop volumineux. Téléversez les médias via le parcours de téléversement au lieu de les intégrer à la requête.
• 40901 — le devis a expiré, la requête a changé après le devis, ou le prix a changé. Demandez un nouveau devis, montrez le nouveau montant à la personne qui paie et faites confirmer de nouveau. Voir Devis et compatibilité des protocoles.
• Autres 409 — traitez-les selon l’opération. Une clé déjà utilisée pour un autre contenu demande une nouvelle Idempotency-Key, correcte, pour la nouvelle requête, et non des nouvelles tentatives sans fin. Voir Erreurs (quand un 409 vaut la peine d’être réessayé).

Soumission sans réponse ni identifiant de tâche

Un dépassement de délai ne vous dit pas si la tâche a été créée. Ne vous contentez pas de la renvoyer avec une nouvelle clé : vous risquez de créer une seconde tâche et d’être facturé une seconde fois.

Les dépassements de délai côté client, les onglets de navigateur fermés et les flux déconnectés n’annulent pas une tâche acceptée, et une tâche acceptée ne peut pas être annulée.

La tâche a échoué

Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.

• Ne réessayez pas sans rien changer : invalid_request, unsupported_combination, content_rejected (le modèle choisi a refusé le contenu — changez le prompt ou le modèle).
• Vaut la peine de réessayer après une pause : rate_limited, upstream_unavailable, upstream_failed.
• Corrigez d’abord : invalid_asset (téléversez de nouveau le fichier), timeout (essayez une durée plus courte ou une résolution plus basse), generation_failed (les mêmes entrées échouent en général de la même façon).

errorMessage explique la raison à l’intention des humains ; il peut s’agir de la raison donnée par le modèle lui-même, en anglais. Faites dépendre votre code uniquement de errorCode. Le tableau complet se trouve dans Erreurs (codes d’échec des tâches). Une nouvelle tentative est une nouvelle tâche, facturée de nouveau si elle réussit.

La tâche reste en file ou en cours

La génération prend du temps : une vidéo longue peut demander plusieurs minutes. Chaque tâche a une échéance côté serveur, renvoyée dans deadlineAt par recordInfo :

• Avant deadlineAt : continuez d’attendre le callback, ou interrogez recordInfo en allongeant les pauses (pas toutes les secondes).
• Après l’échéance : la tâche se termine d’elle-même en expired avec errorCode: "timeout", et sa réservation vous est intégralement rendue. Vous n’avez rien à annuler — et les tâches acceptées ne peuvent de toute façon pas être annulées.

Si une tâche reste running bien au-delà de son deadlineAt, contactez l’assistance en indiquant l’identifiant de la tâche.

Téléversement réussi, entrée refusée

• Vous avez sauté l’étape de validation. Un PUT réussi du fichier ne suffit pas : appelez files/{fileId}/commit, puis passez l’URI spicy:// renvoyée dans le champ d’entrée du modèle. Ne passez jamais l’uploadUrl elle-même.
• Le fichier ne correspond pas au ticket. Vérifiez le Content-Type déclaré, la taille et le format ; une différence renvoie 40003.
• Il a expiré. Un fichier téléversé est utilisable jusqu’au expiresAt indiqué dans la réponse de validation : 1 jour par défaut, ou moins si votre compte supprime les fichiers téléversés à la fin de la tâche. Relancer une tâche peut donc exiger un nouveau téléversement.
• Il appartient à un autre compte. Une URI spicy:// ne fonctionne qu’avec les clés du compte qui l’a téléversée.

Le parcours de téléversement complet est décrit dans Médias.

Callback manquant ou téléchargement expiré

Aucun callback n’est arrivé :

1. Vérifiez que callBackUrl est une adresse https:// joignable depuis Internet. Une adresse en http:// simple n’est pas acceptée.
2. Vérifiez que votre récepteur contrôle la signature sur les octets bruts de la requête, avant toute analyse du JSON, et qu’il répond rapidement par un 2xx. Les traitements longs ont leur place dans votre propre file d’attente. Si la clé de signature a été renouvelée récemment, le récepteur doit utiliser la nouvelle : il n’y a pas de période de chevauchement. Voir Webhooks (secret de signature).
3. Consultez l’historique des livraisons dans Webhooks sur la console, où vous pouvez aussi relancer une livraison.
4. En attendant, lisez la tâche avec recordInfo : l’interrogation reste toujours une solution de repli valable. Voir Webhooks.

Les callbacks peuvent arriver plusieurs fois ou en retard : dédoublonnez-les avant d’exécuter une commande.

Le lien de téléchargement ou le fichier a disparu :

• Un lien de téléchargement dure 20 minutes. Si le résultat est encore conservé, demandez simplement un nouveau lien ; rafraîchir un ancien lien ne fonctionne pas.
• Si le fichier produit est encore en cours de copie vers le stockage, attendez quelques secondes et redemandez.
• Les résultats sont conservés environ 14 jours au plus, et moins si votre compte utilise un réglage de conservation plus court. Une fois que contentState vaut expired ou purged, le fichier est irrécupérable : relancez le modèle. Voir Conservation et destruction.

Le flux s’arrête trop tôt

Vérifiez le statut HTTP et le Content-Type avant d’analyser le flux selon votre protocole. Les morceaux reçus du réseau ne sont pas des événements complets, et une connexion fermée n’est pas un signal de succès : cherchez l’événement final du protocole, un éventuel événement d’erreur, et tenez compte du délai propre à votre application. Ne supposez pas qu’un flux déconnecté était gratuit ni qu’il peut être renvoyé sans frais : la consommation valide enregistrée avant la déconnexion peut être facturée. Conservez le request_id et vérifiez vos relevés de consommation. Voir Texte et streaming.

Permissions d’équipe

• Vous ne pouvez pas créer de clé. Le sélecteur de périmètre, tout en haut de la barre latérale gauche de la console, est réglé sur une équipe où votre rôle est Gestionnaire du budget ou Lecture seule. Créer des clés demande le rôle Propriétaire, Administrateur ou Développeur. Passez sur votre périmètre Personnel, ou demandez le rôle Développeur à un administrateur de l’équipe.
• Vous voyez une tâche, mais pas son prompt ni son résultat. Les gestionnaires du budget et les membres en lecture seule ne voient que l’état, le coût et la consommation.
• Vous ne pouvez pas accepter une invitation. Connectez-vous avec l’adresse e-mail exacte à laquelle l’invitation a été envoyée. Les invitations expirent au bout de 7 jours ; demandez-en une nouvelle si la vôtre a expiré.
• Une clé d’équipe s’arrête avec 40201. Les clés d’équipe dépensent le solde du propriétaire de l’équipe : c’est donc au propriétaire d’ajouter des fonds.

Les rôles et les limites d’équipe sont détaillés dans Console et équipes.

Impossible d’émettre une facture

• Vos coordonnées sont incomplètes. Une facture exige un nom (celui de votre entreprise ou le vôtre), la première ligne d’adresse, la ville et le pays, à saisir une fois en haut de Facturation → Factures.
• Un caractère ne peut pas être imprimé. Seuls les caractères latins, grecs et cyrilliques peuvent figurer sur une facture. Écrivez un nom d’entreprise japonais ou coréen dans sa forme romanisée enregistrée.
• Elle existe déjà. Chaque recharge payée et chaque mois clôturé ne peuvent être facturés qu’une fois ; téléchargez le document existant. Pour corriger des coordonnées, choisissez Réémettre sur ce document.
• Le mois n’est pas disponible. Seuls les mois terminés au cours desquels vous avez dépensé quelque chose peuvent faire l’objet d’un relevé de consommation.

Voir Facturation (factures et relevés de consommation).

Pages liées

Erreurs · Intégration en production · Idempotence · Médias · Webhooks · Texte et streaming · Préparer votre compte