Erreurs

Les échecs de la Platform API utilisent les codes d’état HTTP standard. Presque chaque échec contient une chaîne subcode stable sur laquelle les clients doivent se baser — les codes d’état seuls sont ambigus (403 couvre scope, produit, origin, IP et type de clé).

Envelope

La plupart des erreurs renvoient un wrapper detail de style FastAPI :

{ "detail": "<subcode>" }

Les payloads 429 structurés (map_load_quota_exceeded, b2b_overloaded, org_overloaded, tile_access_restricted) sont des objets plats au niveau supérieur — sans wrapper detail :

{ "error": "map_load_quota_exceeded", "meter": "map_loads", "limit": 50000, "used": 50000 }

Les 429 avec string-detail (map-load hard stops) conservent le wrapper :

{ "detail": "map_load_hard_stop" }

Certains endpoints non streaming signalent les échecs sous forme HTTP 200 avec une clé error — notamment POST /chat/control/route. Un client qui se base uniquement sur le status les considérera comme des réussites. Lisez toujours le body.

Tableau

Statut	Subcode	Signification	Action
401	(no detail)	Clé manquante / invalide / révoquée / expirée	Vérifiez la valeur de la clé et qu’elle n’a pas été révoquée. Viewer n’a pas besoin de clé.
401	publishable_requires_session	Une clé publishable (kld_pk_…) a été envoyée comme bearer direct	Utilisez-la via le SDK, qui l’échange contre une session.
403	insufficient_scope	Clé valide, mais il lui manque le scope de la route	Créez / recréez une clé avec le bon scope (ai / maps / design).
403	tier_capability_not_allowed	La clé stockée avait la capacité, mais le niveau actuel de l’organisation ne l’autorise plus (généralement downgrade Pro→Free)	Mettez à niveau le plan ou utilisez un produit autorisé par le niveau actuel.
403	origin_required	Une clé publishable a été utilisée sans Origin navigateur (par ex. côté serveur)	Les clés publishable sont réservées au navigateur.
403	session_origin_mismatch	Le Origin de la requête n’est pas dans l’allowlist de la clé	Mettez à jour les allowed origins de la clé (voir Obtenir une clé API).
403	product_not_allowed	La clé n’est pas autorisée pour ce produit	Créez une clé avec le produit autorisé (ou utilisez viewer, qui est sans clé).
403	server_key_in_browser	Une server key (kld_sk_…) a été utilisée depuis un navigateur	Les server keys sont uniquement côté serveur ; elles sont aussi bloquées par CORS.
403	ip_not_allowed	Une server key a été utilisée depuis une IP hors de son allowlist	Mettez à jour l’IP allowlist de la clé ou appelez depuis une adresse autorisée.
403	publishable_key_required	Le SDK session exchange a été tenté avec autre chose qu’une clé publishable	Utilisez une clé kld_pk_… lors de l’étape session-exchange.
403	sessions_disabled	L’émission de sessions est désactivée pour ce deployment	Contactez le support — il s’agit d’un état opérationnel, pas d’un paramètre client.
403	sessions_not_configured	L’infrastructure de session n’est pas configurée	Contactez le support.
422	(various)	Body de requête mal formé	Corrigez le payload (voir Endpoints). Lors du mint, unknown_scope / unknown_product indiquent une valeur inconnue ; publishable_live_requires_origins signifie qu’une clé publishable live a été créée sans allowed origins.
429	(flat) map_load_quota_exceeded	L’allocation mensuelle de map-loads de l’organisation est épuisée	Mettez à niveau ou réduisez les chargements de fonds de carte.
429	map_load_hard_stop	L’organisation payante dépasse de 5× son allocation de map-loads	Le service s’arrête ici ; la bande souple au-dessus de l’allocation continue de fonctionner.
429	(flat) tile_access_restricted	Requête Tile rejetée (généralement origin absent de l’allowlist). Contient Retry-After: 3600	Ajoutez l’origin de la page à l’allowlist de la clé ; réessayez après l’intervalle du header.
429	(flat) b2b_overloaded	Le délestage global des requêtes est actif	Réduisez le rythme et réessayez avec jitter.
429	(flat) org_overloaded	Délestage par organisation	Réduisez le rythme et réessayez.
429	limiter_unavailable	Le rate limiter est temporairement inaccessible	Traitez comme transitoire ; réessayez.
429	rate_limited	Trop de requêtes actuellement	Respectez Retry-After.
503	(no detail)	Service de clés temporairement indisponible	Transitoire — réessayez bientôt.

Gestion des clés

Échecs de POST/PATCH/DELETE /shared-api/api-keys/* (Cognito org-admin JWT, pas une platform key) :

Statut	Subcode	Signification
403	free_plan_publishable_only	Les organisations Free ne peuvent créer que des clés publishable.
403	plan_required	L’organisation ne possède aucune ligne de plan API reconnue.
403	tier_capability_not_allowed	Un PATCH a tenté d’élargir une clé au-delà de ce que le niveau actuel de l’organisation autorise.
403	vendor_scope_requires_acknowledgement	Le scope vendor nécessite un indicateur explicite de confirmation par clé.
409	key_limit_reached	L’organisation a atteint la limite de clés par organisation de son plan.

Consultez Obtenir une clé API pour le flux complet de mint et le chemin de mise à jour PATCH.

Erreurs de streaming

Sur un stream SSE, un échec terminal arrive sous forme d’événement error plutôt que de statut HTTP (la réponse a déjà commencé avec 200) :

event: error
data: { "type":"error", "message":"…", "code":"…", "partial_text":"…" }

Traitez un événement error comme la fin de ce stream. Un événement quota en cours de stream n’est pas une erreur — c’est le compteur indiquant le budget restant. Les clients doivent ignorer les noms d’événements inconnus — de nouveaux événements peuvent être ajoutés dans le contrat stable sans changement de version.

CORS "bloqué" dans le navigateur

Si le navigateur signale un blocage CORS sur une vraie requête, le Origin de la requête n’est pas dans l’allowlist de la clé — ce n’est pas un échec d’auth. Consultez CORS & allowed origins.