Erreurs et limites de débit · Docs

Chaque code d'erreur de l'API Node Lodge, son sens et la marche à suivre, et les limites de requêtes par minute et par heure.

Chaque erreur a la même forme. Le statut HTTP indique le type d’échec; code indique lequel.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry in a moment.",
    "reference": "7F3K-92QD"
  }
}

code : stable, fiable pour vos branchements.
message : une phrase destinée à une personne. Elle peut changer.
reference : citez-la au support pour retrouver la requête.
fields : sur VALIDATION_ERROR seulement, les champs en échec, chacun avec un path et un message.

Codes d’erreur

Requête

Code	Statut	Signification	Que faire
`VALIDATION_ERROR`	400	Un champ, la chaîne de requête ou le corps JSON est invalide.	Corrigez les champs listés dans `fields`.
`AMBIGUOUS_CREDENTIALS`	400	La requête porte à la fois un témoin de session de console et une clé d’API.	Envoyez l’un des deux.
`PAYLOAD_TOO_LARGE`	413	Le corps dépasse 64 KiB.	Envoyez un corps plus petit.
`IDEMPOTENCY_MISMATCH`	422	La `Idempotency-Key` a déjà servi avec un autre corps.	Utilisez une nouvelle clé pour une nouvelle requête.

Authentification et accès

Code	Statut	Signification	Que faire
`UNAUTHENTICATED`	401	Aucune session ni clé d’API valide.	Vérifiez l’en-tête `Authorization: Bearer`, ou créez une nouvelle clé.
`FORBIDDEN`	403	Votre rôle, ou le propriétaire de la ressource, n’autorise pas cette action.	Adressez-vous à un propriétaire ou à un administrateur de l’organisation.
`API_KEY_NOT_ALLOWED`	403	Les clés d’API ne peuvent pas appeler cette route, ou la clé n’a pas la portée requise.	Ajoutez la portée à une nouvelle clé, ou passez par la console. Voir Ce qu’une clé peut appeler.
`EMAIL_NOT_VERIFIED`	403	L’adresse courriel du compte n’est pas confirmée.	Ouvrez le lien de confirmation reçu dans votre boîte de réception.
`TERMS_REQUIRED`	403	Les conditions d’utilisation en vigueur ne sont pas acceptées.	Acceptez-les dans la console.
`MFA_REQUIRED`	403	L’action exige l’authentification à deux facteurs.	Activez-la dans Settings.
`STEP_UP_REQUIRED`	403	L’action exige un code à deux facteurs saisi dans les 10 dernières minutes.	Saisissez un nouveau code, puis réessayez.
`MFA_CODE_INVALID`	400	Le code à deux facteurs est erroné ou expiré.	Saisissez le code en cours.
`TOKEN_INVALID`	400	Un lien reçu par courriel est invalide ou expiré.	Demandez un nouveau lien.
`ACCOUNT_THROTTLED`	429	Trop de connexions ou de codes à deux facteurs échoués en 15 minutes.	Patientez 15 minutes.

Sessions, crédit et limites

Code	Statut	Signification	Que faire
`CREDIT_INSUFFICIENT`	402	Le budget dépasse le crédit disponible.	Ajoutez du crédit, ou réduisez le budget.
`FUNDS_INSUFFICIENT`	402	Les fonds disponibles ne couvrent pas la réservation.	Ajoutez du crédit, ou réservez une durée plus courte.
`ACCOUNT_BLOCKED`	402	Un paiement a échoué ou a été annulé : les nouvelles sessions sont bloquées.	Voir Paiement refusé.
`TRUST_LIMIT`	403	La session dépasse les limites de votre compte.	Arrêtez une session, choisissez une autre classe de GPU, ou demandez une limite plus élevée.
`API_KEY_LIMIT`	409	Le budget de la session, sa hausse ou la réservation dépasse un plafond de dépenses de la clé d’API.	Baissez le budget, ou relevez les plafonds de la clé avec Edit limits. Voir Plafonds de dépenses.
`API_KEY_INVALID`	409	La clé qui a réservé la session n’est plus valide.	Utilisez une clé valide.
`MAX_COST_EXCEEDED`	409	La réservation coûte plus que le maximum envoyé.	Relevez le maximum, ou réservez moins de temps.
`BUDGET_EXCEEDED`	409	La session dépasse le plafond de dépenses applicable à cette offre.	Réduisez le budget, ou choisissez une autre offre.
`RESOURCE_UNAVAILABLE`	409	La machine s’est déconnectée ou vient d’être louée.	Choisissez une autre offre.
`PARTNER_UNAVAILABLE`	409	L’offre a changé ou n’existe plus.	Rechargez le catalogue et choisissez de nouveau.
`SESSION_REQUIRED`	409	Les machines en centre de données démarrent en sessions, avec un budget.	Lancez-la avec `POST /v1/sessions`.
`RESERVATION_REQUIRED`	409	Les machines en centre de données se réservent sous forme de réservations sur ce compte.	Réservez-la avec `POST /v1/reservations`, puis démarrez-la.
`INVALID_STATE`	409	L’état de la session ne permet pas cette action, par exemple si elle est déjà terminée.	Lisez la session, puis agissez selon son statut.
`CONFLICT`	409	La ressource existe déjà, ou la même requête est encore en cours.	Lisez la ressource, ou patientez et réessayez.
`NOT_FOUND`	404	La ressource n’existe pas ou ne vous appartient pas.	Vérifiez l’identifiant.

Limites et serveur

Code	Statut	Signification	Que faire
`RATE_LIMITED`	429	Trop de requêtes.	Patientez le nombre de secondes indiqué dans `retry-after`, puis réessayez.
`INTERNAL_ERROR`	500	La requête a échoué sur le serveur.	Réessayez. Si l’erreur persiste, envoyez la `reference` au support.

Limites de débit

Les limites comptent les requêtes par fenêtre de temps. Avec une clé d’API, la limite générale s’applique par clé; sans clé, par adresse IP.

Requêtes	Limite
Toute route de l’API, sauf celles listées ci-dessous	300 à la minute
Inscription et connexion	10 à la minute
Codes à deux facteurs	10 à la minute
Demande de réinitialisation du mot de passe	5 en 15 minutes
Clés d’API : création ou modification des plafonds	30 à l’heure
Clés SSH : ajout	30 à l’heure
Modifications de carte, de crédit et de recharge automatique	20 à l’heure chacune
Support : nouvelle demande	10 à l’heure
Support : réponse, réouverture, résolution	30 à l’heure chacune
Disponibilité publique des GPU	60 à la minute

Chaque réponse indique l’état de sa limite :

x-ratelimit-limit : requêtes autorisées dans la fenêtre.
x-ratelimit-remaining : requêtes restantes.
x-ratelimit-reset : secondes avant la réinitialisation de la fenêtre.

Au-delà de la limite, la réponse est 429 RATE_LIMITED avec un en-tête retry-after en secondes. Patientez ce délai, puis réessayez. Espacez davantage vos tentatives si les 429 se répètent.

Réessayer sans risque

Réessayez les 429, les 500 et les erreurs réseau, jamais les erreurs 4xx qui désignent un champ ou un état.
Envoyez un en-tête Idempotency-Key (8 à 128 lettres, chiffres, - ou _) quand vous réservez ou lancez : une nouvelle tentative avec la même clé et le même corps renvoie le premier résultat au lieu de réserver deux fois.