Erreurs - Agentova API

Toute réponse 4xx/5xx a le même corps :

{
  "error": {
    "code": "automation_not_found",
    "message": "Automation not found in this workspace",
    "details": {}
  }
}

code est stable : c’est sur lui que votre code doit s’appuyer.
message est une explication lisible, en anglais. Il est fait pour être montré à une personne, et sa formulation peut changer sans préavis : ne l’analysez jamais.
details est vide ({}) ou apporte du contexte — le parameter en cause, une valeur max, une reason ou retry_after_seconds, selon l’erreur.

Codes d’erreur

`code`	Statut HTTP	Signification
`invalid_request`	400, aussi 413 et 415	Paramètre de requête ou corps invalide. `413` : le corps dépasse 16 Ko. `415` : le corps n’est pas envoyé en JSON (`Content-Type: application/json`). `details` nomme le `parameter` en cause, ou donne une `reason`.
`invalid_api_key`	401	Clé absente, mal formée, invalide ou révoquée — ces cas sont volontairement indiscernables.
`workspace_access_denied`	403	La clé est valide, mais l’abonnement Agentova de l’espace de travail est impayé, en pause ou incomplet. L’offre gratuite a accès à l’API. Ce n’est pas une permission propre à la clé — la v1 n’en a pas.
`automation_not_found`	404	L’automatisation n’existe pas dans cet espace de travail — même réponse, qu’elle existe ailleurs ou nulle part. Une automatisation supprimée, désactivée dans l’application Agentova ou dont le compte est déconnecté renvoie aussi cette erreur.
`webhook_not_found`	404	L’abonnement webhook n’existe pas dans cet espace de travail. Supprimer un abonnement déjà supprimé renvoie cette erreur — la suppression n’est pas idempotente.
`route_not_found`	404	Chemin ou méthode inconnus — vérifiez le chemin, la méthode HTTP et le préfixe `/v1` de l’URL de base.
`automation_not_controllable`	422	L’automatisation est `draft` ou `error` (`details.status`) : ces états ne peuvent pas être activés ni mis en pause par l’API — corrigez d’abord l’automatisation dans l’application Agentova. Renvoyé aussi quand vous réactivez une automatisation e-mail dont la boîte mail est déjà utilisée par un autre agent actif (`details.reason: account_in_use`) : une boîte mail ne peut servir qu’à un seul agent actif.
`rate_limited`	429	Trop de requêtes — voir Limites de requêtes.
`internal_error`	500	Erreur inattendue du serveur. Réessayez avec un délai croissant ; contactez le support si elle persiste.
`service_unavailable`	503	L’API est temporairement coupée par Agentova. Réessayez plus tard, avec un délai croissant. Pendant ce temps, aucune livraison de webhook n’est créée pour les événements qui surviennent : rattrapez-les avec les routes de liste quand l’API revient — voir Webhooks et signatures.

De nouveaux codes peuvent être ajoutés à la v1. Traitez un code que vous ne connaissez pas d’après son statut HTTP : 4xx signifie que la requête doit changer, 5xx que vous pouvez réessayer plus tard. Voir Versions.

Traiter les erreurs

curl -s "https://core-api.agentova.ai/v1/automations/aut_does_not_exist" \
  -H "Authorization: Bearer agk_live_your_key_here"

{
  "error": {
    "code": "automation_not_found",
    "message": "Automation not found in this workspace",
    "details": {}
  }
}

Testez response.error.code === "automation_not_found" — pas le message, et pas seulement le statut HTTP, puisque plusieurs codes partagent le même (400, 404). Quand réessayer :

Statut	Réessayer ?
`400`, `401`, `403`, `404`, `413`, `415`, `422`	Non — la requête, la clé ou l’espace de travail doit d’abord changer.
`429`	Oui, après le délai indiqué par `Retry-After`.
`500`, `503`, erreurs réseau	Oui, avec un délai qui augmente à chaque essai (backoff exponentiel). `PATCH` peut être répété sans risque : donner à une automatisation le statut qu’elle a déjà ne change rien. Avant de réessayer `POST /webhooks`, vérifiez `GET /webhooks` : la première tentative a peut-être créé l’abonnement.