Ce qu'il faut avant de commencer

Cinq conditions, et rien d'autre. Chacune se vérifie en un appel, et chacune a un code d'erreur qui la désigne — vous n'aurez jamais à deviner laquelle manque.

1. Un compte, avec son courriel vérifié

L'API agit en votre nom : elle exige le même compte que la console, et le même courriel vérifié. Tant qu'il ne l'est pas, tout appel authentifié répond 403 email_not_verified.

Un compte suspendu répond 403 account_suspended. Dans ce cas, seul le support peut rouvrir la porte — aucune clé n'y changera rien.

2. Du crédit, à hauteur de 24 heures

La location à l'heure se paie d'avance. Une commande n'est acceptée que si le solde couvre les 24 premières heures de la machine : 0,44 CAD pour un Nano, 0,80 CAD pour un Starter. En dessous, 402 insufficient_credit, avec le montant manquant au cent près.

Le crédit se recharge dans la console, pas par l'API : engager une dépense est une chose, débiter un moyen de paiement en est une autre. La recharge automatique, elle, se règle une fois dans la console et fonctionne ensuite sans vous.

3. Une clé, avec les bonnes portées

Créée dans Compte → Clés d'API, affichée une seule fois. Ne cochez que ce dont l'outil a besoin : une clé de supervision n'a rien à faire avec vms.destroy. Un appel hors portée répond 403 insufficient_scope en nommant celle qui manquait.

4. De la place dans le quota

Un compte porte cinq machines par défaut. Comptent celles qui occupent des ressources — en attente, actives, suspendues — pas les supprimées. Au-delà, 409 quota_reached. Le plafond se lève à la demande, par ticket ; ce n'est pas une limite commerciale, c'est un garde-fou contre l'emballement d'un script.

GET /v1/account rend l'état du quota à tout moment, avec le solde et l'autonomie. Un script bien élevé le lit avant de commander.

5. Un budget qui n'est pas dépassé

Si vous avez fixé un budget mensuel dans la console, franchir 120 % de ce budget arrête les machines et refuse les commandes (402 budget_cap_reached). Sans budget fixé, rien ne coupe.

Tout vérifier d'un coup

dry_run répond aux cinq questions en une requête, sans rien créer ni rien débiter :

bash

curl -s https://api.ffxf.net/v1/vms \
     -H "Authorization: Bearer $FFXF_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"plan":"nano","region":"montreal","image":"debian-13",
          "hostname":"essai","billing":"hourly","dry_run":true}' | jq .data.checks

Chaque contrôle y figure avec son verdict : quota, stock, billing_mode, credit, budget. Un seul fail et la commande serait refusée, avec ce même code.