Erreurs

Voici la liste complète des erreurs de l’API de la plateforme Kaleidr. Chacune possède un statut HTTP et un code : une courte chaîne stable sur laquelle votre programme peut se baser. Le statut seul ne suffit pas. 403 recouvre de nombreuses causes, et 429 peut signifier aussi bien « ralentissez » que « votre quota est épuisé ».

Commencez par les formats de réponse, car le code ne se trouve pas toujours dans le même champ.

Formats des réponses

Format	Exemple	Utilisé pour
Code encapsulé	{"detail": "origin_not_allowed"}	Presque toutes les erreurs 401, 403, 404, 413, 500 et 503, les codes de dépassement des limites de requête 422, ainsi que deux erreurs 429 (map_load_quota_exceeded et ingest_rate_limited de l’API de téléversement). Le code est la chaîne detail.
Objet plat	{"error": "rate_limited", "detail": "API key rate limit exceeded. Slow down."}	Toutes les autres erreurs 429. Le code est dans error ; detail est une phrase destinée à l’utilisateur. Les erreurs de quota comportent d’autres champs.
Liste de validation	{"detail": [{"loc": ["body", "product"], "msg": "…", "type": "…"}]}	Erreur 422 en cas de corps de requête ou de paramètres mal formés. detail est un tableau contenant une entrée par problème.
Erreur avec 200	{"error": "Route planning failed."}	Uniquement POST /chat/control/route. Voir ci-dessous.

Une fonction permettant d’extraire le code de chacun de ces formats :

async function kaleidrError(res) {
  const body = await res.json().catch(() => ({}));
  const code =
    typeof body.error === 'string' ? body.error :      // flat 429
    typeof body.detail === 'string' ? body.detail :    // wrapped code
    Array.isArray(body.detail) ? 'validation_error' :  // 422
    'unknown_error';
  return { status: res.status, code, body, retryAfter: Number(res.headers.get('retry-after')) || null };
}

Deux en-têtes sont importants : Retry-After, exprimé en secondes dans les réponses 429, et X-Request-Id, lorsqu’il est présent, qui identifie la requête si vous contactez l’assistance.

Authentification : 401

L’API n’accepte pas les identifiants d’authentification.

Code	Quand il survient	Que faire
Invalid or missing API key	Aucun identifiant n’a été envoyé, ou la clé est inconnue, révoquée ou expirée. Également : un jeton de session expiré ; une session dont la clé a été révoquée ou renouvelée sans délai de grâce ; une session dont l’origine ou le produit a été retiré de sa clé ; une session émise avant une rétrogradation d’offre ; une organisation suspendue ou sans offre.	Vérifiez la clé et son état sur kaleidr.com/api-keys. Pour une session, effectuez un nouvel échange. Si une clé valide échoue encore, réessayez après quelques instants : une panne temporaire de la plateforme produit aussi cette réponse.
publishable_requires_session	Une clé publiable (kld_pk_…) a été envoyée à un point de terminaison d’exécution.	Dans le navigateur, laissez le SDK effectuer l’échange ou appelez d’abord POST /sdk/sessions. Sur votre backend, utilisez une clé serveur.

Autorisation : 403

L’API reconnaît les identifiants, mais refuse cette requête.

Code	Quand il survient	Que faire
insufficient_scope	La clé a été créée sans le périmètre d’autorisation requis par ce point de terminaison ou ce produit.	Utilisez une clé disposant de ce périmètre. Impossible d’ajouter des périmètres à une clé existante.
tier_capability_not_allowed	La clé possède le périmètre ou le produit, mais l’offre actuelle de votre organisation ne l’inclut pas. Également renvoyé pour une carte publiée dont l’offre du propriétaire n’inclut pas le chat. Exception : vendor. Une clé portant vendor sous une offre inférieure à Enterprise n’est pas rejetée, mais les réponses sont produites sans vos données.	Changez d’offre ou utilisez un produit inclus dans l’offre.
server_key_in_browser	Une clé serveur (kld_sk_…) a été envoyée avec l’en-tête Origin.	Déplacez l’appel vers votre backend. Si la clé figurait dans le code source de la page, renouvelez-la.
session_origin_mismatch	Un jeton de session a été utilisé depuis une autre origine que celle de son émission, ou une session de carte publiée a été utilisée sans Origin.	Échangez la session sur la page qui doit l’utiliser.
ip_not_allowed	Une clé serveur ou historique dotée d’une liste d’adresses IP autorisées a été utilisée depuis une adresse extérieure à la liste, ou l’adresse de l’appelant n’a pas pu être déterminée.	Effectuez l’appel depuis une adresse autorisée ou modifiez allowed_ips de la clé.
publishable_key_required	POST /sdk/sessions a été appelé avec une clé serveur ou historique.	Utilisez une clé publiable pour l’échange.
origin_required	Il manque l’en-tête Origin lors de l’échange de session.	Effectuez l’échange depuis une page de navigateur.
origin_not_allowed	L’origine de la page ne figure pas dans les origines autorisées de la clé ni dans les domaines autorisés de la carte publiée.	Ajoutez l’origine exacte à la clé ou le domaine à la carte.
product_not_allowed	La clé est limitée à certains produits et la requête en vise un autre. À l’échange : le product demandé n’appartient pas aux produits autorisés de la clé publiable. À l’exécution : une clé serveur ou historique appelle un point de terminaison d’un produit non autorisé, par exemple une clé limitée à tile qui appelle /chat/*.	Modifiez allowed_products ou utilisez une autre clé.
chat_disabled	Échange de carte publiée : la Kaleidr AI de la carte n’active pas la fonctionnalité demandée.	Activez Control Tower ou Popup Window dans la tuile Kaleidr AI de la carte dans Studio.
feature_not_granted	Une session de carte publiée ouverte pour le chat en popup a été utilisée sur /chat/control/stream. Chaque fonctionnalité a sa propre session.	Échangez une session avec "feature": "control_tower", que la carte accorde tant que Control Tower est activé.
owner_has_no_organization	Échange de carte publiée : le propriétaire de la carte n’appartient à aucune organisation à facturer.	Le propriétaire doit créer ou rejoindre une organisation.

Introuvable : 404

Code	Quand il survient	Que faire
not_found	Échange de carte publiée : aucune carte publiée ni aucun lien de partage ne possède ce share_id.	Vérifiez l’identifiant et que la carte est publiée.
sessions_disabled	L’échange des sessions est désactivé sur la plateforme.	Vous ne pouvez pas résoudre ce problème vous-même. Contactez l’assistance.
Not Found	Le chemin n’existe pas.	Vérifiez l’URL dans les Points de terminaison, notamment le préfixe /inference-api/b2b/v1.

Validation : 422

Le corps ou les paramètres de la requête ne correspondent pas au format accepté par le point de terminaison. detail est un tableau ; chaque entrée contient loc, qui indique le champ, et msg, qui décrit le problème.

{
  "detail": [
    { "type": "missing", "loc": ["body", "product"], "msg": "Field required", "input": {} }
  ]
}

Corrigez la requête ; ne la réessayez pas telle quelle. Deux points de terminaison de diffusion, /chat/summary/stream et /chat/button/stream, renvoient 500 plutôt que 422 si le corps est mal formé, sauf pour un champ trop long (voir ci-dessous).

Limites des requêtes : 422 avec un code

Une requête bien formée qui dépasse une limite de taille reçoit également 422, mais sous le format encapsulé : detail contient une chaîne de code et non un tableau. Aucun frais n’est facturé.

{ "detail": "conversation_too_long" }

Code	Point de terminaison	Quand il survient	Que faire
too_many_messages	/chat/control/stream	messages contient plus de 400 entrées.	N’envoyez que les échanges les plus récents.
message_too_long	/chat/control/stream	Le content d’un message dépasse 64 000 caractères.	Raccourcissez le message.
conversation_too_long	/chat/control/stream	La somme des champs content dépasse 200 000 caractères.	Supprimez les échanges les plus anciens et renvoyez la requête.
invalid_session_id	/chat/control/stream	session_id dépasse 128 caractères ou contient autre chose que lettres, chiffres, _, ., : ou -.	Utilisez un identifiant respectant ce format, comme un UUID.
lang_too_long	/chat/control/stream	lang dépasse 35 caractères.	Envoyez une balise BCP 47 telle que pt-BR.
invalid_layout	/chat/control/stream	layout dépasse 16 caractères.	Envoyez guide tant que le viewer affiche sa mise en page guide, ou omettez le champ.
field_too_long	/chat/summary/stream, /chat/button/stream	Un champ texte ou une liste dépasse sa limite.	Raccourcissez le champ. Les limites sont indiquées dans les Points de terminaison.

Les limites du flux de chat sont détaillées dans les Points de terminaison.

Requête trop volumineuse : 413

Code	Quand il survient	Que faire
request_too_large	Le corps de la requête dépasse 2 MiB, ou 5 MiB pour un point /design/*. Le corps est {"detail": "request_too_large"}. Aucun frais n’est facturé.	Envoyez moins de données : réduisez la conversation ou les lignes d’exemple d’une requête de conception. Ne renvoyez pas le même corps.
request_body_too_large	Une requête de gestion des clés ou de données d’entreprise sous /shared-api dépasse 1 MiB, ou dépasse 32 MiB pour l’import POST /shared-api/datahub/ingests.	Envoyez un corps plus petit. Pour les imports, voir Importer vos données d’entreprise.

Une requête déclarant une taille très supérieure aux limites de tous les points de terminaison peut être rejetée à la périphérie du réseau, avant d’atteindre l’API. Cette réponse ne comporte aucun corps JSON Kaleidr et donc aucun code à lire : envoyez moins de données.

Une requête rejetée pour sa taille, comme toute requête rejetée avant traitement, n’est pas facturée et ne réserve ensuite ni crédits IA ni place de concurrence.

Limites de quota et de débit : 429

Lisez le corps de la réponse avant de décider s’il faut réessayer.

Code	Champ	Retry-After	Quand cela se produit	Que faire
quota_exceeded	error	secondes jusqu’à reset_at	Les crédits d'IA de votre organisation ne suffisent pas à couvrir l'appel, ou celui-ci dépasserait le plafond mensuel de la clé. Ce code est également renvoyé par l'appel de proposition de correspondance de l'API d'importation.	Ne réessayez pas. Attendez reset_at, ajoutez des crédits ou augmentez le plafond de la clé.
rate_limited	error	5	Le nombre maximal de requêtes par minute pour la clé a été atteint. Cela se produit aussi en cas d'échanges de session trop nombreux pour une clé, une carte publiée ou une adresse.	Attendez le nombre de secondes indiqué par Retry-After, puis réessayez avec un délai aléatoire supplémentaire.
org_overloaded	error	5	Votre organisation a trop d'appels en cours simultanément.	Attendez qu'un appel se termine, puis réessayez. Fermez les flux dont vous n'avez plus besoin.
b2b_overloaded	error	5	L'API a atteint sa capacité maximale pour l'ensemble des appelants.	Attendez le nombre de secondes indiqué par Retry-After, puis réessayez en augmentant progressivement le délai d'attente.
limiter_unavailable	error	5	Le limiteur de débit n'a pas pu répondre.	Réessayez sous peu. Le problème ne vient pas de votre débit de requêtes.
visitor_limit_reached	error	5	Un visiteur du chat d'une carte publiée a dépassé sa limite de requêtes par minute ou par jour.	Indiquez au visiteur de réessayer plus tard.
map_load_quota_exceeded	detail	aucun	POST /sdk/sessions pour tile : le quota de chargements de cartes de l'organisation est épuisé.	Ne réessayez pas. Attendez la réinitialisation de la période ou ajoutez un forfait de chargements de cartes.

Le corps de quota_exceeded contient les valeurs numériques :

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "product": "b2b",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 4999100,
  "remaining": 900,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

C’est le corps qu’obtient une clé serveur. Une requête effectuée avec un jeton de session (issu de l’échange d’une clé publiable ou d’une session visiteur de carte publiée) reçoit un corps plus court, qui ne divulgue ni l’offre ni l’utilisation de l’organisation :

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "meter": "b2b.tokens",
  "reset_at": "2026-11-01T04:00:00+00:00",
  "reset_in_seconds": 1296000
}

Les champs, la variante avec plafond par clé et le code de traitement sont détaillés dans les Quotas et limites de débit.

Erreurs du serveur : 5xx

Statut	Code	Quand il survient	Que faire
500	An internal error occurred. Please try again.	Défaillance inattendue.	Réessayez une fois après un court délai.
500	map_design_analyze_failed	POST /design/analyze n’a pas pu analyser le tableau. Non facturé.	Vérifiez les colonnes et lignes d’exemple puis réessayez.
500	Summary stream error	POST /chat/summary/stream n’a pas pu démarrer : corps illisible ou requête concernant un bâtiment sans address. Un champ trop long renvoie plutôt 422 field_too_long.	Corrigez le corps.
500	Button chat stream error	POST /chat/button/stream n’a pas pu démarrer : corps illisible ou sans query. Un champ trop long renvoie plutôt 422 field_too_long.	Corrigez le corps.
503	sessions_not_configured	L’échange de sessions est indisponible à cause d’une défaillance de la plateforme.	Réessayez ; contactez l’assistance si le problème persiste.
503	share_grant_unavailable	Échange de carte publiée : impossible de lire les paramètres de la carte.	Réessayez bientôt.

Erreur avec le statut 200

POST /chat/control/route renvoie 200 lorsqu’un itinéraire ne peut pas être calculé :

{ "error": "Route planning failed." }

La réponse contient error et aucun action. Un client qui ne vérifie que le statut considérera l’appel comme réussi, puis échouera en lisant action. Vérifiez toujours la présence de error dans le corps. Le texte est conçu pour être affiché à l’utilisateur. Détails : Itinéraires.

GET /retrieval/geocode/forward présente un comportement semblable : une recherche qui échoue en interne renvoie 200 avec une liste results vide, tout comme une recherche sans résultat.

Erreurs dans un flux

Tout ce qui précède s’applique avant le début d’un flux : une requête de diffusion refusée produit une erreur HTTP ordinaire. Dès que la réponse est 200 et que les trames circulent, une défaillance est signalée par un événement error :

event: error
data: {"type": "error", "code": "upstream_stall", "message": "The AI service stopped responding. Please try again.", "partial_text": "The Louvre sits"}

Flux	code	Quand il survient	Que faire
/chat/control/stream	upstream_stall	La réponse ne progresse plus ou le flux atteint sa durée maximale d’environ 10 minutes.	Proposez de réessayer. Conservez partial_text s’il est utile.
/chat/control/stream	absent	Toute autre défaillance pendant la génération de la réponse.	Affichez message. Un nouvel essai peut réussir.
/chat/summary/stream	absent	Le résumé a échoué.	Affichez message ou continuez sans résumé.
/spot/overview/stream	absent	L’aperçu a échoué ou la référence ref ne peut pas être décrite. L’événement contient ref dans ce dernier cas : une référence poi: ou region: absente du point, place: sans hint.name, ou un bâtiment ou une adresse que l’API ne décrit pas.	N’affichez aucun aperçu. Ne relancez pas un événement comportant ref.
/chat/button/stream	aucun	Ce flux n’envoie pas d’événement error. Une défaillance ferme la connexion sans end.	Considérez comme échoué tout flux fermé sans end.

Règles applicables à tous les flux :

• Un événement error remplace end. Il ne peut être suivi que d’un éventuel événement quota.
• Une connexion qui se ferme sans end ni error a échoué.
• L’événement quota n’est pas une erreur. Il s’agit d’un rapport d’utilisation envoyé après end ou error. Pour un flux lu avec un jeton de session, il ne contient que type, meter et reset_at.
• Un nom d’événement inconnu n’est pas une erreur. Ignorez-le.

Un flux qui échoue ou qui est interrompu reste facturé. Pour /chat/control/stream, le coût n’est jamais inférieur à une estimation de la conversation envoyée et peut donc dépasser la réservation initiale : voir Facturation d’un flux. Une nouvelle tentative constitue une autre requête, facturée séparément.

Erreurs masquées par le navigateur

Lorsque l’origine ou les identifiants sont refusés, la réponse ne comporte pas d’en-tête CORS ; le navigateur masque le statut et le corps à votre code. La page voit une erreur CORS dans la console et un fetch rejeté ; le SDK journalise une erreur contenant [kaleidr:<product>].

Pour lire le véritable code, ouvrez l’onglet Réseau et sélectionnez la requête en échec. Les cas courants sont origin_not_allowed, Invalid or missing API key et server_key_in_browser. Voir CORS et origines autorisées.

Une réponse 4xx sans aucun corps JSON Kaleidr provient de la périphérie du réseau, avant l’API. Il s’agit soit d’une limitation du débit (patientez et réessayez plus tard), soit d’une requête dont la taille déclarée dépasse largement toutes les limites des points de terminaison (envoyez moins de données ; réessayer sans changement reproduira la même réponse).

Hôte des tuiles

Les requêtes vers tile.kaleidr.com qui ne proviennent pas d’une intégration Kaleidr utilisant une clé publiable valide depuis une origine autorisée reçoivent :

Statut	Code	Retry-After	Que faire
429	tile_access_restricted (dans error, avec message et docs)	3600	Utilisez le produit Tile avec une clé publiable et ajoutez l’origine de la page à la liste des origines autorisées de la clé, si cette liste existe.

Gestion des clés

Erreurs provenant de https://api.kaleidr.com/shared-api/api-keys, utilisé par la page API Keys et accessible avec le jeton d’accès de votre compte. Toutes sont au format encapsulé.

Statut	Code	Quand il survient	Que faire
401	variable	Aucun jeton d’accès de compte valide. Une clé de plateforme n’est pas acceptée ici.	Reconnectez-vous.
403	org_admin_required	Votre compte n’est ni propriétaire ni administrateur de l’organisation.	Adressez-vous à un propriétaire ou administrateur.
403	plan_required	L’organisation n’a pas d’offre.	Choisissez une offre sur kaleidr.com/billing.
403	free_plan_publishable_only	Une clé serveur a été demandée avec l’offre Free. Même erreur si une clé serveur ou historique est renouvelée sous Free.	Créez une clé publiable ou passez à Pro.
403	tier_capability_not_allowed	Création de clé : scopes ou allowed_products mentionne un élément non autorisé par l’offre. En pratique, il s’agit de demander vendor sous Free ou Pro : la demande est refusée, que vendor_acknowledged soit envoyé ou non, et aucune clé n’est créée. Modification de clé : allowed_products désigne un produit exclu de l’offre ou, sous Free, une liste vide.	vendor nécessite Enterprise. Dans les autres cas, indiquez les périmètres et produits autorisés par l’offre.
404	key_not_found	Aucune clé avec cet identifiant dans l’organisation. La modification et la révocation retrouvent une clé quel que soit son état, si bien que révoquer une clé déjà révoquée renvoie 200. Le renouvellement exige une clé active et renvoie ce code pour une clé révoquée.	Vérifiez l’identifiant. Pour un renouvellement, la clé est peut-être révoquée.
409	key_limit_reached	L’organisation a atteint le nombre maximal de clés actives de son offre (Free 2, Pro 10, Enterprise 25).	Révoquez une clé ou renouvelez-en une plutôt que d’en créer une autre.
409	key_already_rotated	La clé a déjà été renouvelée, que son délai de grâce soit terminé ou non. Elle ne peut pas être renouvelée à nouveau ; toute modification supprimant expires_at ou le fixant après la fin du délai de grâce est refusée. Une valeur expires_at antérieure et les autres champs restent modifiables.	Utilisez la clé de remplacement.
409	key_expired	Une clé jamais renouvelée a expiré et la modification comprend expires_at. Une clé expirée ne peut pas recevoir une nouvelle date d’expiration ; ses autres champs restent modifiables.	Créez une nouvelle clé.
413	request_body_too_large	Le corps dépasse 1 MiB.	Envoyez un corps plus petit.
422	unknown_scope	scopes contient une valeur autre que ai, maps, design, vendor.	Corrigez la liste.
422	unknown_product	allowed_products contient une valeur autre que chat, editor, viewer, tile.	Corrigez la liste.
422	vendor_scope_requires_acknowledgement	Sous Enterprise, une clé publiable avec vendor a été demandée sans vendor_acknowledged: true. Sous Free et Pro, la même demande renvoie 403 tier_capability_not_allowed.	Lisez le périmètre vendor, puis envoyez ce champ.
422	no_fields_to_update	Demande de modification sans champ modifiable.	Envoyez au moins un champ.
422	liste de validation	Origine ou adresse IP mal formée, date d’expiration passée ou nom invalide.	Corrigez le champ indiqué dans loc.
500	insert_failed, session_unavailable	Une défaillance de la plateforme.	Réessayez.
503	api_key_pepper_not_configured	Impossible de créer des clés à cause d’une défaillance de la plateforme.	Réessayez ; contactez l’assistance si le problème persiste.

Importation de données métier

Erreurs des routes d’import sous https://api.kaleidr.com/shared-api/datahub et de l’appel de proposition de correspondance. La liste complète, avec les limites de fichier et de champ à l’origine de chaque erreur 422, figure dans Importer vos données d’entreprise. Voici les erreurs qui refusent une requête avant lecture du fichier, et celles liées aux appels de dépublication et de suppression d’une version :

Statut	Code	Quand il survient	Que faire
403	org_admin_required	Le compte n’est ni propriétaire ni administrateur de l’organisation. Également renvoyé par la proposition de correspondance.	Adressez-vous à un propriétaire ou administrateur.
403	vendor_data_not_on_plan	L’offre de l’organisation ne permet pas d’importer des données d’entreprise. Cette fonction est réservée à Enterprise. Renvoyé pour l’import, la publication, le retraitement et la proposition de correspondance, jamais pour la lecture, la dépublication ou la suppression.	Passez à Enterprise. GET /shared-api/datahub/limits indique, quelle que soit l’offre et sans refuser la demande, si l’organisation peut importer. Sous Free et Pro, ajoutez plutôt des données à une carte dans Kaleidr Studio : voir Jeux de données sur une carte.
404	release_not_found	Lors d’une dépublication ou suppression, aucune version de cet identifiant n’existe dans l’organisation, notamment après la fin de sa suppression.	Pour une suppression, considérez que l’opération est déjà effectuée.
409	org_ingest_in_progress	Un autre import de l’organisation est en cours de traitement. Renvoyé lors de l’import, de la publication et du retraitement.	Attendez sa fin puis recommencez.
409	release_not_published	Dépublication demandée pour un brouillon ou une version en échec.	Rien à dépublier. Supprimez-la plutôt.
409	release_is_published	Suppression demandée pour la version publiée.	Dépubliez-la, puis supprimez-la.
413	request_body_too_large	La requête d’import dépasse 32 MiB.	Envoyez un fichier plus petit. Le fichier lui-même peut atteindre la limite de taille de votre organisation.
422	{ "errors": [ … ] } dans detail	Le fichier dépasse une limite de lignes ou de taille, un champ d’un ensemble JSON dépasse sa longueur maximale, ou le JSON est trop profondément imbriqué. La raison d’une limite contractuelle précise la limite et l’offre.	Lisez chaque raison et corrigez le fichier.
429	ingest_rate_limited	L’organisation a lancé 30 imports au cours de la dernière heure.	Attendez puis recommencez.
429	une phrase dans detail	Le compte a effectué 30 propositions de correspondance dans la dernière heure. Le corps ne possède pas de champ error.	Attendez puis recommencez.
429	quota_exceeded dans error	Proposition de correspondance : les crédits IA de l’organisation sont épuisés. Le corps est la réponse de quota standard.	Attendez reset_at, ajoutez des crédits ou effectuez la correspondance manuellement.

Importation de jeux de données dans Kaleidr Studio

Cette section ne fait pas partie de l’API de plateforme authentifiée par clé. Elle décrit la réponse reçue par Kaleidr Studio lorsqu’un utilisateur connecté ajoute un jeu de données à une carte dans le panneau Data et que l’import est refusé en raison de sa taille. Aucune clé API n’intervient. Il existe deux refus aux significations différentes :

Statut	Code	Quand il survient	Que faire
402	quota_exceeded	L’import d’un nouveau jeu de données dépasse l’une des limites de l’offre de l’organisation : lignes dans un jeu, taille d’un fichier ou lignes dans tous les jeux de données de l’organisation. limit_key indique la limite. Les données déjà enregistrées sont conservées. Studio affiche le message et un lien pour changer d’offre.	Importez un fichier plus petit ou supprimez les jeux inutiles. Sous Free, passez à Pro. Sous Pro ou Enterprise, contactez Kaleidr pour augmenter le total de l’organisation ; les limites de lignes par jeu et de taille par fichier ne peuvent pas dépasser les plafonds de la ligne suivante.
400	VALIDATION_ERROR	Le fichier ou jeu de données dépasse un plafond valable pour toutes les offres : fichier de plus de 64 MiB, jeu de données de plus de 100 000 lignes, fichier géographique de plus de 50 000 entités ou image superposée de plus de 16 MiB. Le code est dans error. Changer d’offre ne permet pas cet import.	Divisez le fichier en plusieurs fichiers plus petits. Ne renvoyez pas le même fichier et ne proposez pas de changement d’offre.

La réponse dépend de la taille, pas seulement de l’offre. Le plafond général est vérifié en premier : un fichier de plus de 64 MiB ou un jeu de plus de 100 000 lignes produit 400 sous Free, Pro et Enterprise. Le 402 concerne un import respectant ce plafond mais dépassant la limite de l’organisation, par exemple un fichier de 40 MiB sous Free où la limite est de 32 MiB.

402 quota_exceeded

Le corps est un objet de description de problème contenant également les champs Studio error et message. Le code figure dans error et code, et la phrase dans message et detail :

{
  "error": "quota_exceeded",
  "message": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "type": "https://errors.kaleidr.com/datasets/quota_exceeded",
  "title": "Quota Exceeded",
  "status": 402,
  "detail": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "code": "quota_exceeded",
  "limit_key": "studio.data.rows.max",
  "limit": 250000,
  "used": 248500,
  "tier": "free",
  "upgrade_url": "https://kaleidr.com/pricing"
}

Champ	Signification
error, code	Toujours quota_exceeded. La même valeur deux fois.
message, detail	La même phrase deux fois. Elle décrit clairement la limite et est destinée à être affichée à l’utilisateur.
type	Toujours https://errors.kaleidr.com/datasets/quota_exceeded.
title	Toujours Quota Exceeded.
status	Toujours 402.
limit_key	La limite ayant refusé l’import. Voir le tableau suivant.
limit	La limite de l’organisation, dans l’unité correspondante.
used	Pour le total, les lignes déjà détenues par l’organisation. Pour les deux autres, les lignes ou les MiB de cet import.
tier	L’offre de l’organisation : free, pro ou enterprise. Vaut unknown si l’offre n’a pas pu être lue ; les limites Free s’appliquent alors.
upgrade_url	Adresse pour changer d’offre.

limit_key	Limite	Unité de limit et used	Phrase
studio.dataset.rows.max	Lignes dans un jeu de données	Lignes	« Votre offre autorise 50 000 lignes par jeu de données. Importez un fichier plus petit ou changez d’offre. »
studio.dataset.file.mb	Taille d’un fichier importé	MiB	« Votre offre autorise des fichiers jusqu’à 32 MB. Importez un fichier plus petit ou changez d’offre. »
studio.data.rows.max	Lignes de tous les jeux de l’organisation	Lignes	« Votre offre autorise 250 000 lignes dans tous les jeux de données de votre organisation. Supprimez un jeu ou changez d’offre pour en ajouter davantage. »

Les nombres de ces phrases correspondent aux limites Free ; le message reçu contient les limites de votre organisation. Affichez-le à l’utilisateur et basez votre traitement sur code et limit_key. Cette erreur 402 diffère de l’erreur 429 quota_exceeded de l’API de plateforme, qui concerne les crédits IA.

400 VALIDATION_ERROR

Le corps possède deux champs et aucun membre supplémentaire de description du problème :

{
  "error": "VALIDATION_ERROR",
  "message": "File is larger than 64 MB."
}

Motif du refus	message
Fichier de plus de 64 MiB	« Le fichier dépasse 64 MB. »
Jeu de données de plus de 100 000 lignes	« Maximum de 100000 enregistrements par jeu de données »
Fichier géographique de plus de 50 000 entités	« <filename> contient plus de 50000 entités. Divisez-le ou simplifiez sa géométrie avant de l’importer. »
Image superposée de plus de 16 MiB	« L’image superposée dépasse 16 MB. »

Le même statut et le même code sont renvoyés pour d’autres problèmes liés à un fichier importé, comme un format non lu par Studio ou un fichier sans lignes exploitables ; message précise le problème. Traitez toute réponse 400 à un import comme « ce fichier ne peut pas être ajouté en l’état » et affichez message.

Voir aussi

• Authentification et périmètres : identifiants et échange de session.
• Quotas et limites de débit : détail des réponses 429.
• Contrat SSE : événements d’un flux.
• Dépannage : problèmes classés par symptômes.