OpenAI insufficient_quota et credit_balance_exhausted : pourquoi la nouvelle tentative n’aidera pas

L'API OpenAI renvoie 429 avec le type d'erreur insufficient_quota lorsque votre compte n'a plus de crédits ou dépasse une limite de dépenses ou d'utilisation. Il s'agit du même code d'état que pour une limitation de débit, mais attendre quelques secondes ne résoudra pas le problème. L’accès revient uniquement une fois que quelqu’un ajoute des crédits, augmente une limite ou que la période mensuelle est réinitialisée. OpenAI indique que réessayer après des erreurs de facturation, de dépenses ou de quota ne rétablira pas l’accès à l’API, et que vous devez consulter error.code pour en identifier la cause précise. Pour plus d’informations, consultez Codes d’erreur.

À quoi ressemblent les erreurs de quota d’OpenAI

Chacune de ces erreurs retourne 429. Le error.type peut toujours être insufficient_quota ; vérifiez donc error.code pour savoir lequel vous avez reçu.

Comparez-les avec les erreurs « Limite de débit atteinte », comme rate_limit_exceeded et slow_down. Ceux-ci sont temporaires et une nouvelle tentative après une courte attente fonctionne généralement. Pour plus d’informations, consultez les erreurs OpenAI « Rate limit reached ».

Comment gérer les erreurs de quota OpenAI

1. Lisez error.code, pas seulement l’état. Un 429 seul ne vous indique pas s’il faut réessayer. Traitez les 4 codes du tableau comme « stop » et les codes de limitation de débit comme « attendre et réessayer ».
2. Arrêtez de réessayer. N’envoyez pas à nouveau la requête et ne laissez pas une boucle de nouvelle tentative continuer à appeler l’API. Jusqu’à ce que quelqu’un corrige le problème de facturation, chaque requête échoue de la même façon.
3. Mettez en pause les appels qui échoueraient. Une erreur de quota signifie que les requêtes suivantes de la même organisation ou du même projet échouent également. Ignorez-les au lieu de les envoyer un par un et d'attendre l'erreur.
4. Indiquez à l’utilisateur. Expliquez que la fonctionnalité IA n’est pas disponible pour l’instant et que le reste de votre application fonctionne.
5. Configurez une alerte pour vous-même. Consignez le code avec un niveau de gravité élevé ou alertez la personne responsable de la facturation. La solution ne se trouve pas dans votre code : quelqu'un doit donc être informé.

Le SDK Python OpenAI réessaie les réponses 429 deux fois par défaut. Quel que soit le nombre de nouvelles tentatives effectuées, votre code finit par recevoir RateLimitError avec le code d'erreur de facturation. C'est à ce moment-là que vous devez arrêter :

import logging

import openai
from openai import OpenAI

client = OpenAI()
logger = logging.getLogger(__name__)

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}
billing_error: str | None = None


def ask(prompt: str) -> str:
    global billing_error
    if billing_error:
        raise RuntimeError("AI features are paused until billing is fixed.")
    try:
        response = client.responses.create(model="gpt-4.1", input=prompt)
        return response.output_text
    except openai.RateLimitError as error:
        if error.code in BILLING_CODES:
            billing_error = error.code
            logger.critical("OpenAI billing error: %s", error.code)
        raise

L’indicateur reste défini jusqu’à ce que votre application redémarre. Si votre application s'exécute pendant une longue période, prévoyez un autre moyen de rétablir le fonctionnement, par exemple une action d'administration après la résolution du problème de facturation.

Comment tester que votre application gère les erreurs de quota OpenAI

Vous voyez rarement une erreur de quota pendant le développement. Votre compte de test dispose de crédits et votre utilisation est faible. Ainsi, la façon dont vous testez la gestion des quotas détermine si vous trouvez les bogues avant que vos utilisateurs ne le fassent.

Essayez-le dans votre application

Dev Proxy intercepte les requêtes de votre application vers api.openai.com et retourne des erreurs OpenAI, tandis que votre application continue d’appeler les URL réelles. Le openai-throttling préréglage inclut une credit_balance_exhausted erreur parmi les erreurs de limite de débit. Elle retourne 429 avec un type insufficient_quota et sans en-tête Retry-After. Vous pouvez donc vérifier que votre application s’arrête au lieu de réessayer.

Téléchargez le preset et démarrez Dev Proxy avec celui-ci :

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Pour tester uniquement les erreurs de quota, modifiez le fichier du openai-errors.json preset et conservez uniquement la credit_balance_exhausted réponse. Pour tester les codes de limite de dépense et d’utilisation, ajoutez des réponses avec la même structure et une autre code.

Exécutez ensuite votre application comme d’habitude et regardez ce qu’elle fait. Pour installer Dev Proxy, consultez Configurer Dev Proxy.

Étapes suivantes

Voir aussi

• Erreurs OpenAI « Limite de requêtes atteinte » : ce qu’elles signifient et comment les gérer
• 429 Trop de demandes : ce que cela signifie et comment le gérer
• Simuler des erreurs à partir d’API OpenAI
• GenericRandomErrorPlugin