"Edge Function returned a non-2xx status code" : la vraie erreur

Vous appuyez dans votre app sur le bouton qui appelle une Edge Function, et au lieu d'un résultat votre app affiche ceci :

Edge Function returned a non-2xx status code

C'est la même phrase quoi qu'il se soit passé. Une clé manquante, une fonction qui a planté, une requête refusée avant que votre code tourne : toutes donnent "Edge Function returned a non-2xx status code", donc le message seul ne vous dit presque rien de ce qu'il faut réparer.

Ce qu'il ne vous dit pas, c'est que la raison est déjà arrivée. L'erreur est revenue dans la même réponse que cette phrase, et supabase-js ne vous la lit pas. Chercher la phrase vous donne les suppositions des autres. Lire la réponse vous donne la vôtre.

Que signifie "Edge Function returned a non-2xx status code" ?

Votre fonction a répondu, et la réponse était une erreur. C'est tout ce que dit la phrase.

Toute réponse sur le web porte un code de statut, un nombre à trois chiffres qui dit comment la requête s'est passée. Tout ce qui est dans les 200 veut dire que ça a marché. Quand votre app appelle une fonction via supabase.functions.invoke, supabase-js regarde ce nombre, et s'il est hors des 200, il remet à votre app une phrase fixe à la place des données. La phrase est écrite mot pour mot dans supabase-js lui-même, et l'erreur qui la porte s'appelle FunctionsHttpError.

Imaginez l'appel comme une lettre envoyée à un bureau à l'arrière. Le bureau répond à ce que vous avez demandé ou renvoie la lettre. Quand elle revient, supabase-js lit le tampon sur l'enveloppe et vous dit qu'elle a été renvoyée. Il n'ouvre pas l'enveloppe. Le mot à l'intérieur dit pourquoi, et le bureau a tenu un registre de tout ce qui s'est passé pendant qu'il avait votre lettre.

Deux proches parents se ressemblent et veulent dire autre chose. Failed to send a request to the Edge Function signifie qu'aucune réponse lisible n'est revenue du tout, et dans un navigateur c'est souvent un en-tête CORS manquant, que l'article sur ce message couvre. Et si plusieurs parties sans rapport de votre app ont cassé au même moment, vérifiez si c'est Supabase ou votre app avant d'ouvrir le moindre code.

Où est la vraie erreur ?

À deux endroits, et vous pouvez lire les deux sans changer une ligne de code.

La réponse elle-même. Ouvrez votre app en ligne dans Chrome, Edge ou Firefox, appuyez sur F12, choisissez l'onglet Network et refaites ce qui a échoué. Cliquez sur la requête dont l'adresse contient /functions/v1/ suivi du nom de votre fonction. Sa colonne Status donne le nombre, et son onglet Response montre ce que la fonction a renvoyé avec : un message écrit par votre propre code, un court contenu JSON venu de la plateforme de Supabase, ou les mots Internal Server Error.

Si vous, ou l'outil qui écrit votre code, pouvez modifier l'appel, le guide de gestion des erreurs de Supabase montre comment lire la même réponse dans l'app, parce que la réponse d'origine voyage avec l'erreur sous le nom error.context :

const { data, error } = await supabase.functions.invoke('your-function', { body })
if (error) console.log(error.context.status, await error.context.text())

Le registre de la fonction. Dans le tableau de bord Supabase, ouvrez Edge Functions, choisissez la fonction et lisez deux onglets. Invocations liste chaque requête avec son code de statut et sa durée. Logs contient ce que le guide de journalisation de Supabase appelle les événements de plateforme, les exceptions non interceptées et les messages de log personnalisés, c'est-à-dire tout ce que votre code a affiché avec console.log ou console.error. Reproduisez l'échec une fois, notez l'heure et lisez les deux onglets à cette minute-là.

Lisez d'abord le code de statut

Le nombre vous dit jusqu'où votre requête est allée avant d'être renvoyée, et c'est ce qui décide où la raison est écrite.

Les significations viennent de la référence des codes de statut de Supabase et de sa page des limites. Un 404 n'a besoin de rien de plus que ce tableau : comparez le nom de la fonction dans votre app à la liste du tableau de bord, et vérifiez qu'elle est déployée dans le projet auquel votre app parle. Les autres lignes ont chacune une section ci-dessous.

500 : votre fonction a tourné et échoué

Quelque chose dans votre code a levé une erreur, et l'onglet Logs a la ligne.

La page de Supabase sur cette erreur la coupe en deux. Si la réponse dit exactement Internal Server Error, votre code a planté et le log montre le type d'erreur et la ligne où elle s'est produite, par exemple TypeError: Cannot read properties of undefined. Si la réponse dit autre chose, votre code a écrit ce message lui-même et renvoyé le 500 exprès, alors cherchez dans la fonction le statut qu'elle a envoyé.

Une cause mérite d'être écartée avant toutes les autres dans une fonction qui appelle OpenAI, Stripe ou n'importe quelle API payante : un secret qui existe sur votre machine et pas dans votre projet en ligne.

Dans la fonction, un secret se lit avec Deno.env.get('OPENAI_API_KEY'). Quand aucun secret de ce nom n'est défini, la documentation de Deno indique que cela renvoie undefined au lieu d'échouer. La fonction continue donc, construit une requête avec le mot undefined à la place de la clé, et l'envoie. OpenAI répond par son propre 401, "Incorrect API key provided", et votre fonction le transmet ou s'effondre en lisant une réponse qu'elle n'attendait pas. Dans l'image de l'enveloppe : le bureau a ouvert votre lettre, est allé au tiroir où la clé devait se trouver, l'a trouvé vide, et a renvoyé un mot sur une mauvaise clé.

La réparation se fait sur la page Edge Function Secrets de votre projet Supabase. Le guide des secrets de Supabase indique qu'une fonction lit un nouveau secret immédiatement, donc sans redéploiement, et qu'aucun nom de secret ne peut commencer par SUPABASE_, car ce préfixe est réservé aux valeurs que Supabase définit pour vous. Un secret défini pour le développement local reste sur votre machine ; le projet en ligne a sa propre liste.

401 : refusée avant que votre code tourne

Si la réponse dit Invalid JWT ou Missing authorization header, votre fonction n'a jamais vu la requête. La plateforme de Supabase l'a refusée à la porte.

Cette porte, c'est une vérification appelée verify_jwt, active par défaut, qui lit l'en-tête Authorization de chaque requête avant que votre code tourne. La page de Supabase sur le 401 donne trois façons d'y échouer :

• La clé ne correspond pas à celles de votre projet. Par exemple une clé copiée d'un autre projet, ou une ancienne encore réglée quelque part après une rotation.
• Il n'y a pas d'en-tête Authorization du tout. supabase-js en ajoute un pour vous. Un simple fetch vers l'adresse de la fonction, ou un webhook venu d'un autre service, ne le fait pas.
• Votre projet utilise les nouvelles clés de signature de Supabase. La vérification intégrée ne comprend que l'ancien format, et la solution de Supabase est de couper la vérification pour cette fonction.

Ce dernier point va plus loin qu'un seul cas. Supabase recommande désormais de couper la vérification intégrée et de gérer l'authentification directement dans le code de votre fonction. La recommandation a deux moitiés, et la seconde est celle qu'on oublie.

Si le 401 est arrivé avec un message écrit par votre propre code, la plateforme a laissé passer la requête et votre fonction l'a refusée, ou a transmis un 401 du service qu'elle appelait, souvent le secret vide de la section sur le 500. C'est aussi une autre vérification que celle derrière PGRST301 sur vos requêtes de base de données, qui a sa propre page. Si le journal de la fonction affiche invalid claim: missing sub claim, elle a demandé à Supabase Auth qui appelait et a reçu la clé de votre projet au lieu d'un utilisateur connecté, ce que l'article sur ce message retrace.

546 et 504 : à court de ressources ou de temps

Supabase arrête une fonction qui consomme trop, et les deux nombres disent quelle limite elle a touchée.

546, c'est le calcul. La page des limites donne à une fonction 256 Mo de mémoire et à chaque requête 2 secondes de temps CPU. Dépassez l'une ou l'autre et la réponse indique Function failed due to not having enough compute resources (please check logs), avec le code WORKER_RESOURCE_LIMIT (les anciens logs disent WORKER_LIMIT). L'onglet Logs dit CPU Time exceeded ou Memory limit exceeded. La page de Supabase sur le 546 donne en exemples le traitement d'images, les embeddings d'IA et le web scraping, et sa réponse est d'en faire moins par requête ou de confier la partie lourde à un autre service.

504, c'est le temps. Une fonction qui n'envoie aucune réponse en 150 secondes reçoit un 504. La limite CPU ne compte que le temps où votre code calcule vraiment : la page des limites précise qu'elle n'inclut pas les entrées-sorties asynchrones, et attendre le réseau en est. Une fonction qui attend un modèle d'IA lent ne dépense donc pas de CPU. Elle fait tourner l'horloge de 150 secondes, et quand celle-ci s'arrête vous recevez un 504 et non un 546.

Deux correctifs qui aggravent les choses

Deux changements font disparaître ce message en quelques minutes, et les deux vous laissent dans une situation pire que l'erreur.

Appeler l'API depuis la page à la place. Le moyen le plus rapide pour qu'une fonction qui échoue cesse d'échouer, c'est de ne plus s'en servir : mettre la clé dans une variable VITE_ et appeler OpenAI directement depuis votre frontend. Ça marche du premier coup. Ça met aussi la clé dans le fichier que chaque visiteur télécharge, parce que ce préfixe est une instruction de compiler la valeur dans votre bundle, et n'importe qui peut l'y lire. Parmi les apps en ligne que nous avons scannées, une clé OpenAI est apparue dans le JavaScript de 33 d'entre elles, et ce qu'un inconnu peut en faire a son propre article.

Couper la vérification et s'arrêter là. Faire disparaître un 401 en coupant verify_jwt, c'est la première moitié du conseil de Supabase lui-même. Le guide de configuration de Supabase dit clairement ce que cela fait seul : n'importe qui peut alors invoquer votre Edge Function sans JWT valide. L'adresse de votre fonction est dans votre frontend, lisible par tous. Si la fonction détient une clé OpenAI, un inconnu peut maintenant la dépenser à travers vous. Si elle utilise la clé secrète du projet, que Supabase place dans l'environnement de chaque fonction, la requête d'un inconnu tourne avec une clé qui passe outre chaque règle de row level security que vous avez écrite.

La seconde moitié, un contrôle de qui appelle écrit dans la fonction, tient en quelques lignes. Déplacer un secret dans une Edge Function les donne, et explique pourquoi même la vérification par défaut laisse passer plus d'appelants que son nom ne le laisse croire.

La première erreur se voit de l'extérieur, et c'est comme ça que nous l'avons comptée. Notre scan gratuit lit le JavaScript de votre app en ligne comme le ferait un inconnu et nomme chaque clé qu'il trouve, en précisant si elle a sa place là. Il prend environ 20 secondes et ne demande aucun compte : scannez votre app.

Garder la clé là où vous l'avez mise

Le correctif d'aujourd'hui peut être défait par le prompt de la semaine prochaine. Un builder à qui l'on demande de refaire marcher une fonctionnalité est libre de prendre le raccourci ci-dessus, et votre app continue de tourner pendant ce temps.

Reeve Monitor vérifie toutes les heures pour vous :

• les neuf vérifications toutes les heures, sur trois apps au plus
• un e-mail le jour où un nouveau scan note votre app moins bien que le précédent ; une clé secrète dans votre JavaScript plafonne à elle seule la note à D
• si l'app répond, toutes les 60 secondes
• un rapport mensuel de ce qui a été vu

Une fonction qui tourne avec votre clé secrète passe outre chaque règle de row level security. Reeve Care garde une copie de votre base Supabase là où rien dans votre projet ne peut l'atteindre.

• une copie chiffrée selon un calendrier, conservée sur le stockage de Reeve dans l'UE, en dehors de votre compte Supabase
• chaque copie vérifiée avant de compter, en comptant les lignes de chaque table
• une restauration en un clic qui sauvegarde ce qui est là avant de le remplacer
• vos fichiers téléversés aussi, dès que vous connectez un accès Storage
• tout ce que fait Monitor

Quoi faire maintenant

Le contrôle de qui appelle est l'étape la plus facile à sauter, et le guide des secrets dans les Edge Functions la traite en entier. La checklist de sécurité en 10 minutes couvre ce qui reste souvent ouvert dans une app tout juste lancée.