Erreurs et limites de débit

L'API publique Armox utilise les codes de statut HTTP standard et un format JSON d'erreur cohérent.

Format de réponse d'erreur

{ "error": "Human-readable message" }

Exemples :

{ "error": "Invalid API key" }

{ "error": "Insufficient credits. Required 1000, available 200" }

Codes d'erreur

Code	Signification	Cause typique
`400`	Bad Request	Payload invalide, champ requis manquant, modèle invalide
`401`	Unauthorized	Clé API Bearer manquante ou invalide
`402`	Payment Required	Crédits insuffisants
`403`	Forbidden	Restrictions de plan/accès
`404`	Not Found	Ressource/job/app introuvable
`409`	Conflict	Le job ne peut pas être annulé dans son état actuel
`429`	Too Many Requests	Limite de débit par clé dépassée
`500`	Internal Server Error	Erreur backend inattendue

Limites de débit

La limitation de débit est appliquée par clé API sur une fenêtre glissante de 60 secondes.

Chaque réponse authentifiée réussie inclut :

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Si la limite est dépassée, l'API retourne :

statut 429
corps d'erreur { "error": "Rate limit exceeded" }
en-tête Retry-After: 60

Gestion des réponses 429

Stratégie recommandée :

lisez l'en-tête Retry-After
attendez avant de réessayer
utilisez un backoff exponentiel avec jitter pour les 429 répétés
évitez les tentatives synchronisées entre les workers

Exemple de tentative en JavaScript

async function requestWithRetry(url, options, retries = 3) {
  for (let attempt = 0; attempt <= retries; attempt += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("Retry-After") || 2);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error("Exceeded retry attempts");
}

Crédits et facturation

les crédits sont facturés lorsqu'une exécution est acceptée
les jobs échoués sont remboursés par le flux d'exécution
surveillez l'utilisation via GET /api/v1/account

Erreurs courantes en production

Invalid API key : clé erronée/expirée/révoquée
Public API access requires ... : abonnement non éligible
Insufficient credits ... : rechargez les crédits ou réduisez le coût d'exécution
Rate limit exceeded : ajoutez du backoff et une file d'attente

Liste de vérification pour le débogage

vérifiez que Authorization: Bearer ... est présent
vérifiez le chemin et la méthode de l'endpoint
journalisez les identifiants de requête/job dans votre application
capturez les en-têtes de réponse pour l'observabilité des limites de débit
persistez les payloads échoués pour les rejouer