Référence des erreurs

Cette page documente chaque erreur que l'API Scan Cert-IX peut retourner, organisée par catégorie. Utilisez-la comme référence lors du débogage de vos intégrations.

Format de réponse

Toutes les réponses d'erreur suivent une enveloppe JSON cohérente :

{
  "success": false,
  "error": "Description lisible de l'erreur",
  "code": "CODE_MACHINE_LISIBLE"
}

Champ	Description
success	Toujours false pour les erreurs
error	Message descriptif expliquant le problème
code	Code d'erreur stable et lisible par machine pour le traitement programmatique

Codes de statut HTTP

Statut	Catégorie	Signification
400	Erreur client	Requête invalide — JSON malformé, champs requis manquants, paramètres invalides
401	Authentification	Clé API manquante, invalide, expirée ou révoquée
403	Autorisation	Clé valide mais portée insuffisante, IP non autorisée ou type d'analyse non permis
404	Non trouvé	La ressource n'existe pas ou n'appartient pas à votre tenant
409	Conflit	Conflit d'état de ressource (ex. : annuler une analyse déjà terminée)
429	Limite de débit	Limite de débit ou quota dépassé
500	Erreur serveur	Erreur interne — contactez le support si persistante
503	Indisponible	Service temporairement indisponible — réessayez avec backoff

Erreurs d'authentification (401)

Code	Message	Cause	Résolution
MISSING_API_KEY	La clé API est requise	Pas d'en-tête X-API-Key fourni	Ajoutez l'en-tête X-API-Key à votre requête
INVALID_API_KEY	Clé API invalide	Le format est incorrect ou la clé n'existe pas	Vérifiez que la clé commence par cix_sk_
KEY_EXPIRED	La clé API a expiré	La clé a dépassé sa date expiresAt	Créez une nouvelle clé ou effectuez une rotation
KEY_REVOKED	La clé API a été révoquée	La clé a été explicitement révoquée	Créez une nouvelle clé
KEY_SUSPENDED	La clé API a été suspendue	La clé a été suspendue par un administrateur	Contactez l'administrateur de votre organisation

Erreurs d'autorisation (403)

Code	Message	Cause	Résolution
INSUFFICIENT_SCOPE	Portée insuffisante : nécessite {scope}	La clé n'a pas la portée requise	Créez une nouvelle clé avec la portée requise
SCAN_TYPE_NOT_ALLOWED	Type d'analyse {type} non autorisé	allowedScanTypes de la clé n'inclut pas ce moteur	Mettez à jour la clé ou créez-en une autorisant ce type
IP_NOT_ALLOWED	IP source non dans la liste autorisée	L'IP de la requête n'est pas dans allowedIpAddresses	Ajoutez l'IP source à l'allowlist ou supprimez les restrictions
TENANT_SUSPENDED	Le compte du tenant est suspendu	Le compte de votre organisation a été suspendu	Contactez [email protected]

Erreurs d'analyse (400 / 404 / 409)

Code	HTTP	Message	Résolution
SCAN_NOT_FOUND	404	Analyse non trouvée	Vérifiez l'ID d'analyse et le paramètre scanType
INVALID_SCAN_TYPE	400	Type d'analyse invalide : {type}	Utilisez un moteur valide : nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel
INVALID_TARGET	400	Format de cible invalide	Vérifiez que la cible correspond au format attendu pour le type d'analyse
INVALID_PRIORITY	400	Priorité invalide : {value}	Utilisez : critical, high, normal ou low
SCAN_ALREADY_COMPLETED	409	L'analyse est déjà terminée	Impossible d'annuler une analyse ayant atteint un état terminal
SCAN_ALREADY_CANCELLED	409	L'analyse est déjà annulée	L'analyse a déjà été annulée
SCAN_ALREADY_FAILED	409	L'analyse a déjà échoué	Impossible d'annuler une analyse en échec
RESULTS_NOT_READY	409	Les résultats ne sont pas encore disponibles	Attendez que l'analyse atteigne le statut completed

Erreurs de modèles (400 / 404)

Code	HTTP	Message	Résolution
TEMPLATE_NOT_FOUND	404	Modèle d'analyse non trouvé	Vérifiez l'ID du modèle
TEMPLATE_NAME_REQUIRED	400	Le nom du modèle est requis	Fournissez un champ name
DUPLICATE_TEMPLATE_NAME	400	Le nom du modèle existe déjà	Utilisez un nom unique

Erreurs de webhooks (400 / 404)

Code	HTTP	Message	Résolution
WEBHOOK_NOT_FOUND	404	Webhook non trouvé	Vérifiez l'ID du webhook
INVALID_WEBHOOK_URL	400	L'URL du webhook doit utiliser HTTPS	Assurez-vous que votre URL commence par https://
WEBHOOK_URL_UNREACHABLE	400	Impossible de joindre l'URL du webhook	Vérifiez que votre endpoint est accessible publiquement
INVALID_WEBHOOK_EVENT	400	Type d'événement invalide : {event}	Utilisez des événements valides : scan.completed, scan.failed, scan.started, scan.cancelled
WEBHOOK_DISABLED	409	Webhook désactivé suite à des échecs consécutifs	Réactivez avec PATCH et corrigez votre endpoint

Erreurs de limite de débit et quotas (429)

Code	Message	Résolution
RATE_LIMIT_EXCEEDED	Limite de débit dépassée. Réessayez dans {N} secondes.	Implémentez un backoff exponentiel ; vérifiez l'en-tête Retry-After
QUOTA_EXCEEDED	Quota mensuel d'analyses dépassé	Mettez à niveau votre plan ou attendez la prochaine période de facturation

Erreurs de validation (400)

Code	Message	Résolution
INVALID_JSON	Le corps de la requête n'est pas du JSON valide	Vérifiez votre syntaxe JSON
MISSING_REQUIRED_FIELD	Champ requis manquant : {field}	Incluez tous les champs requis
INVALID_FIELD_TYPE	Le champ {field} doit être de type {type}	Corrigez le type de données du champ
INVALID_PAGE	La page doit être un entier positif	Utilisez page ≥ 1
INVALID_LIMIT	La limite doit être entre 1 et 100	Utilisez limit entre 1 et 100

Erreurs serveur (500 / 503)

Code	Message	Résolution
INTERNAL_ERROR	Une erreur interne du serveur s'est produite	Réessayez avec backoff ; contactez le support si persistant
SERVICE_UNAVAILABLE	Service temporairement indisponible	Réessayez avec backoff ; vérifiez status.cert-ix.com
DATABASE_ERROR	L'opération de base de données a échoué	Réessayez ; contactez le support si persistant
KAFKA_ERROR	L'opération de file de messages a échoué	Réessayez ; la file d'attente peut être temporairement congestionnée

Guide de dépannage

« 401 — MISSING_API_KEY »

Vérifiez : Passez-vous l'en-tête X-API-Key ?

# ✅ Correct
curl -H "X-API-Key: cix_sk_..." https://api.cert-ix.com/scan-api/api/v1/scans

# ❌ Incorrect — clé dans les paramètres URL
curl "https://api.cert-ix.com/scan-api/api/v1/scans?apiKey=cix_sk_..."

# ❌ Incorrect — utilisation de l'en-tête Authorization
curl -H "Authorization: Bearer cix_sk_..." https://api.cert-ix.com/scan-api/api/v1/scans

« 403 — INSUFFICIENT_SCOPE »

Votre clé n'a pas la portée requise. Vérifiez quelle portée est nécessaire dans le message d'erreur, puis créez une nouvelle clé ou mettez à jour l'existante avec la portée requise.

« 404 — SCAN_NOT_FOUND »

Causes les plus courantes :

1. Mauvais scanType — Si vous avez créé une analyse zap, vous devez interroger avec ?scanType=zap
2. Mauvais ID d'analyse — Revérifiez l'UUID
3. Tenant différent — Les clés d'organisations différentes ne peuvent pas voir les analyses des autres

« 429 — RATE_LIMIT_EXCEEDED »

Implémentez un backoff exponentiel :

import time

def requete_avec_backoff(func, max_retries=5):
    for tentative in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** tentative))
        print(f"Limité. Réessai dans {retry_after}s...")
        time.sleep(retry_after)
    raise Exception("Nombre maximum de tentatives dépassé")

« 429 — QUOTA_EXCEEDED »

Options :

1. Mettez à niveau votre plan pour un quota plus élevé
2. Attendez la prochaine période de facturation (1er du mois, minuit UTC)
3. Optimisez — Réduisez les analyses inutiles ou utilisez des modèles avec des options plus restreintes

« 500 — INTERNAL_ERROR »

1. Réessayez — La plupart des erreurs 500 sont transitoires
2. Vérifiez status.cert-ix.com pour les informations de panne
3. Contactez [email protected] avec l'ID de requête de la réponse d'erreur

---

Prochaines étapes :

• Exemples de code →
• Prise en main →
• Authentification →