Erreurs

L’API utilise les statuts HTTP usuels : 2xx succès, 4xx erreur de la requête, 5xx erreur du service. Toute erreur a le même format :

JSON

{
  "error": {
    "code": "validation_failed",
    "message": "`threshold` is required for `large_transfer`.",
    "details": { "field": "threshold" }
  }
}

Champ	Sens
`code`	Identifiant stable, en `snake_case`. Programmez sur ce champ : il ne change jamais au sein de v1.
`message`	Explication en anglais pour le développeur. Le texte peut être amélioré sans préavis : ne l’analysez pas et ne l’affichez pas tel quel à vos utilisateurs finaux.
`details`	Objet, éventuellement vide, avec les informations utiles à la correction (champ fautif, limite atteinte, règles concernées…).

v1 peut ajouter de nouveaux codes : traitez un code inconnu selon son statut HTTP.

Codes par statut#

400 Requête invalide#

Code	Cause
`invalid_body`	Corps JSON mal formé (`details.reason`).
`invalid_query`	Paramètre de requête invalide : `limit`, `cursor`, date, `severity`, `status`, `state`… (`details.field`).
`invalid_idempotency_key`	`Idempotency-Key` vide, trop longue ou non ASCII.

401 Non authentifié#

Code	Cause
`missing_api_key`	Pas d’en-tête `Authorization: Bearer`.
`invalid_api_key`	Clé inconnue ou mal formée.
`api_key_revoked`	Clé révoquée.
`api_key_expired`	Clé expirée.

403 Refusé#

Code	Cause
`insufficient_scope`	La clé n’a pas la portée exigée (`details.required_scope`, `details.key_scopes`).
`workspace_suspended`	Espace suspendu.
`account_under_review`	Compte propriétaire en cours de vérification (`details.reason`).
`plan_required`	L’offre ne comprend pas l’API (`details.plan`).
`plan_limit_reached`	Limite de l’offre atteinte (`details.resource` : `addresses`, `rules`, `channels`, `chains` ; `limit`, `current`, `plan`).
`plan_feature_unavailable`	Fonction non comprise dans l’offre, par exemple `immediate_alert` (`details.feature`).
`channel_kind_not_in_plan`	Type de canal non compris dans l’offre (`details.allowed_kinds`).

404, 405#

Code	Cause
`not_found`	Ressource inexistante, d’un autre espace, ou identifiant mal formé ; route inconnue.
`method_not_allowed`	Méthode non permise sur cette ressource.

409 Conflit#

Code	Cause
`address_already_watched`	Adresse déjà surveillée sur cette chaîne (`details.id` : son identifiant).
`address_in_use`	Adresse utilisée par des règles actives (`details.rules`) : mettez-les d’abord en pause.
`channel_in_use`	Canal utilisé par des règles actives (`details.rules`).
`channel_inactive`	Canal désactivé : réactivez-le avant un test ou un renvoi.
`change_already_pending`	Une pause ou une suppression différée attend déjà sur cette règle.
`notification_already_queued`	Notification déjà en file d’envoi.
`notification_grouped`	Alerte comptée dans un récapitulatif : renvoyez le récapitulatif (`details.notification_id`).
`idempotency_in_progress`	Requête de même `Idempotency-Key` encore en cours (`Retry-After: 1`).

413, 415#

Code	Cause
`payload_too_large`	Corps de plus de 1 Mio sur une requête avec `Idempotency-Key`.
`unsupported_media_type`	Corps sans `Content-Type: application/json`.

422 Données invalides#

Code	Cause
`validation_failed`	Champ invalide (`details.field`) ; corps qui ne suit pas le schéma : champ obligatoire absent, mauvais type ou champ inconnu (`details.reason`) ; chaîne ou canal inconnu.
`url_not_allowed`	URL de webhook refusée par la protection SSRF (`details.reason`).
`idempotency_key_reused`	`Idempotency-Key` déjà utilisée pour une requête différente.

Les corps de requête refusent les champs inconnus : une faute de frappe dans un nom de champ donne 422 validation_failed plutôt qu’un champ silencieusement ignoré.

429 Trop de requêtes#

Code	Cause
`rate_limited`	Débit par seconde de la clé dépassé (`Retry-After: 1`).
`daily_quota_exceeded`	Quota quotidien de l’offre atteint (`Retry-After` jusqu’à minuit UTC).

5xx Erreur du service#

HTTP	Code	Cause
500	`internal_error`	Erreur interne. Réessayez plus tard ; écrivez à support@aicscan.io si elle persiste.
503	`channel_kind_unavailable`	Type de canal (Telegram ou helloMe) momentanément indisponible sur le service.

Que faire selon le statut#

Statut	Réessayer ?
`400`, `401`, `403`, `404`, `405`, `413`, `415`, `422`	Non : corrigez la requête, la clé ou l’offre.
`409`	Selon le code : `idempotency_in_progress` oui, après `Retry-After` ; les autres demandent une action.
`429`	Oui, après `Retry-After`.
`500`, `502`, `503`, `504`	Oui, avec un délai croissant, et la même `Idempotency-Key` pour un `POST`.

Obtenir de l’aide#

Si une erreur persiste ou ne s’explique pas, écrivez à support@aicscan.io avec le nom de votre espace, la route appelée, l’heure (UTC), le statut HTTP et le code reçu, ainsi que le préfixe de la clé (aic_k3J9xQ2a). N’envoyez jamais la clé complète : en cas de doute, révoquez-la depuis la page Clés d’API.