Guides

Erreurs et limites

Format

Toutes les erreurs ont la même forme :

Code
{
  "error": {
    "code": "origin_not_allowed",
    "message": "Cette page n'est pas autorisée pour cette clé.",
    "request_id": "req_7c1e…"
  }
}

Basez votre code sur code, qui est stable ; message est une explication lisible qui peut évoluer.
Le request_id est aussi dans l'en-tête X-Request-Id. Donnez-le au support (contact@twimi.ai) : il permet de retrouver la requête dans nos journaux.

Codes

HTTP	`code`	Sens	Que faire
400	`invalid_request`	requête mal formée ; le message nomme les champs	corriger la requête
401	`invalid_key`	clé absente, inconnue, révoquée, ou d'un autre environnement ; avec un jeton : la clé qui a ouvert la conversation a été révoquée	vérifier la clé et l'environnement
401	`token_expired`	jeton de conversation périmé	rouvrir avec `resume`
401	`invalid_token`	jeton invalide	ouvrir une nouvelle conversation
403	`origin_not_allowed`	page non déclarée pour cette clé publique	faire déclarer la page
403	`formula_not_allowed`	fonction non incluse dans la formule	—
403	`deployment_suspended`	déploiement suspendu	contacter Twimi
403	`secret_key_required`	route réservée à la clé secrète (`/v1/usage`)	appeler depuis le serveur
403	`invalid_link`	lien de fichier modifié ou expiré	relire la fiche de l'avatar
404	`not_found`	adresse inconnue	—
404	`avatar_not_found`	avatar hors du déploiement	vérifier `avatar_id`
404	`conversation_not_found`	conversation inconnue ou terminée	ouvrir une nouvelle conversation
409	`voice_limit_reached`	voix indisponible : forfait, plafond, fusible ou réponse de plus de 1 500 caractères	continuer par écrit (voir `X-Twimi-Voice-Reason`)
410	`conversation_expired`	conversation de plus de 10 minutes	ouvrir une nouvelle conversation
413	`audio_too_large`	son de plus de 5 Mo (`/transcriptions`)	raccourcir l'enregistrement
429	`rate_limited`	trop de requêtes	attendre la durée de `Retry-After`
500	`internal_error`	erreur de notre côté ; aucun détail interne n'est renvoyé	réessayer, sinon support
502	`voice_unavailable`, `transcription_unavailable`, `brain_unavailable`, `knowledge_unavailable`	service momentanément indisponible	réessayer un peu plus tard

Sur /messages, la réponse étant en flux, un échec arrive comme un événement :

Code
data: {"type": "error", "code": "brain_unavailable", "message": "…"}

Limites de débit

Quoi	Limite
Ouvertures de conversation	60 par minute et par déploiement
Questions (`/messages`)	20 par minute et par conversation
Morceaux de voix (`/speech`)	60 par minute et par conversation
Transcriptions	20 par minute et par conversation

Au-delà : 429 rate_limited, avec l'en-tête Retry-After (en secondes).

Code
async function appel(url, options, essais = 3) {
  const res = await fetch(url, options);
  if (res.status === 429 && essais > 0) {
    const attente = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, attente * 1000));
    return appel(url, options, essais - 1);
  }
  return res;
}

Autres limites

Quoi	Limite
Question (`message`)	1 000 caractères
Morceau de voix (`text`)	2 000 caractères
Voix par réponse (un tour)	1 500 caractères, tous morceaux compris
Son d'une question orale	5 Mo, 30 secondes
Durée d'une conversation	10 minutes
Validité d'un jeton	30 minutes

Last modified on October 28, 2026

Voix et décompte