Riferimento errori

Questa pagina documenta ogni errore che l'API Scan di Cert-IX può restituire, organizzato per categoria.

Formato della risposta

{
  "success": false,
  "error": "Descrizione leggibile dell'errore",
  "code": "CODICE_LEGGIBILE_DALLA_MACCHINA"
}

Codici di stato HTTP

Stato	Categoria	Significato
400	Errore del client	Richiesta non valida — JSON malformato, campi obbligatori mancanti
401	Autenticazione	Chiave API mancante, non valida, scaduta o revocata
403	Autorizzazione	Chiave valida ma scope insufficiente, IP non permesso o tipo di scansione non consentito
404	Non trovato	La risorsa non esiste o non appartiene al vostro tenant
409	Conflitto	Conflitto di stato della risorsa (es.: annullare una scansione già completata)
429	Limite di velocità	Limite di velocità o quota superata
500	Errore del server	Errore interno — contattate il supporto se persiste
503	Non disponibile	Servizio temporaneamente non disponibile — riprovate con backoff

Errori di autenticazione (401)

Codice	Messaggio	Causa	Soluzione
MISSING_API_KEY	La chiave API è obbligatoria	Nessun header X-API-Key fornito	Aggiungete l'header X-API-Key alla vostra richiesta
INVALID_API_KEY	Chiave API non valida	Il formato è errato o la chiave non esiste	Verificate che la chiave inizi con cix_sk_
KEY_EXPIRED	La chiave API è scaduta	La chiave ha superato la sua data expiresAt	Create una nuova chiave o effettuate una rotazione
KEY_REVOKED	La chiave API è stata revocata	La chiave è stata esplicitamente revocata	Create una nuova chiave
KEY_SUSPENDED	La chiave API è stata sospesa	La chiave è stata sospesa da un amministratore	Contattate l'amministratore della vostra organizzazione

Errori di autorizzazione (403)

Codice	Messaggio	Causa	Soluzione
INSUFFICIENT_SCOPE	Scope insufficiente: richiede {scope}	La chiave non ha lo scope richiesto	Create una nuova chiave con lo scope necessario
SCAN_TYPE_NOT_ALLOWED	Tipo di scansione {type} non consentito	allowedScanTypes della chiave non include questo motore	Aggiornate la chiave o createne una che permetta questo tipo
IP_NOT_ALLOWED	IP sorgente non è nella lista consentita	L'IP della richiesta non è in allowedIpAddresses	Aggiungete l'IP sorgente alla lista o rimuovete le restrizioni
TENANT_SUSPENDED	L'account del tenant è sospeso	L'account della vostra organizzazione è stato sospeso	Contattate [email protected]

Errori di scansione (400 / 404 / 409)

Codice	HTTP	Messaggio	Soluzione
SCAN_NOT_FOUND	404	Scansione non trovata	Verificate l'ID della scansione e il parametro scanType
INVALID_SCAN_TYPE	400	Tipo di scansione non valido: {type}	Usate un motore valido: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel
INVALID_TARGET	400	Formato obiettivo non valido	Verificate che l'obiettivo corrisponda al formato atteso
INVALID_PRIORITY	400	Priorità non valida: {value}	Usate: critical, high, normal o low
SCAN_ALREADY_COMPLETED	409	La scansione è già completata	Non è possibile annullare una scansione in stato terminale
SCAN_ALREADY_CANCELLED	409	La scansione è già annullata	La scansione è già stata annullata
SCAN_ALREADY_FAILED	409	La scansione è già fallita	Non è possibile annullare una scansione fallita
RESULTS_NOT_READY	409	I risultati non sono ancora disponibili	Attendete che la scansione raggiunga lo stato completed

Errori dei template (400 / 404)

Codice	HTTP	Messaggio	Soluzione
TEMPLATE_NOT_FOUND	404	Template di scansione non trovato	Verificate l'ID del template
TEMPLATE_NAME_REQUIRED	400	Il nome del template è obbligatorio	Fornite un campo name
DUPLICATE_TEMPLATE_NAME	400	Il nome del template esiste già	Usate un nome univoco

Errori dei webhook (400 / 404)

Codice	HTTP	Messaggio	Soluzione
WEBHOOK_NOT_FOUND	404	Webhook non trovato	Verificate l'ID del webhook
INVALID_WEBHOOK_URL	400	L'URL del webhook deve usare HTTPS	Assicuratevi che il vostro URL inizi con https://
WEBHOOK_URL_UNREACHABLE	400	Impossibile raggiungere l'URL del webhook	Verificate che il vostro endpoint sia raggiungibile pubblicamente
INVALID_WEBHOOK_EVENT	400	Tipo di evento non valido: {event}	Usate eventi validi: scan.completed, scan.failed, scan.started, scan.cancelled
WEBHOOK_DISABLED	409	Webhook disattivato per fallimenti consecutivi	Riattivate con PATCH e correggete il vostro endpoint

Errori di limite di velocità e quote (429)

Codice	Messaggio	Soluzione
RATE_LIMIT_EXCEEDED	Limite di velocità superato. Riprovate tra {N} secondi.	Implementate backoff esponenziale; verificate l'header Retry-After
QUOTA_EXCEEDED	Quota mensile di scansioni superata	Aggiornate il vostro piano o attendete il prossimo periodo di fatturazione

Errori di validazione (400)

Codice	Messaggio	Soluzione
INVALID_JSON	Il corpo della richiesta non è JSON valido	Verificate la vostra sintassi JSON
MISSING_REQUIRED_FIELD	Campo obbligatorio mancante: {field}	Includete tutti i campi obbligatori
INVALID_FIELD_TYPE	Il campo {field} deve essere di tipo {type}	Correggete il tipo di dato del campo
INVALID_PAGE	La pagina deve essere un intero positivo	Usate page ≥ 1
INVALID_LIMIT	Il limite deve essere compreso tra 1 e 100	Usate limit tra 1 e 100

Errori del server (500 / 503)

Codice	Messaggio	Soluzione
INTERNAL_ERROR	Si è verificato un errore interno del server	Riprovate con backoff; contattate il supporto se persiste
SERVICE_UNAVAILABLE	Servizio temporaneamente non disponibile	Riprovate con backoff; verificate status.cert-ix.com
DATABASE_ERROR	L'operazione del database è fallita	Riprovate; contattate il supporto se persiste
KAFKA_ERROR	L'operazione della coda messaggi è fallita	Riprovate; la coda potrebbe essere temporaneamente congestionata

Guida alla risoluzione dei problemi

« 401 — MISSING_API_KEY »

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

# ❌ Errato — chiave nei parametri URL
curl "https://api.cert-ix.com/scan-api/api/v1/scans?apiKey=cix_sk_..."

« 404 — SCAN_NOT_FOUND »

Cause più comuni:

1. scanType errato — Se avete creato una scansione zap, dovete interrogare con ?scanType=zap
2. ID scansione errato — Verificate l'UUID
3. Tenant diverso — Le chiavi di organizzazioni diverse non possono vedere le scansioni delle altre

« 429 — RATE_LIMIT_EXCEEDED »

Implementate backoff esponenziale:

import time

def richiesta_con_backoff(func, max_tentativi=5):
    for tentativo in range(max_tentativi):
        response = func()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** tentativo))
        time.sleep(retry_after)
    raise Exception("Numero massimo di tentativi superato")

---

Prossimi passi:

• Esempi di codice →
• Per iniziare →
• Autenticazione →