Recupero errori API

L'API di convalida OSCAL Secani restituisce errori come dettagli del problema RFC 9457 con il tipo di supporto application/problem+json. Un client può diramarsi nella stable code, spettacolo title E detail a una persona e seguirla resolution senza analizzare la prosa. IL type E documentation i campi rimandano alla voce corrispondente in questa pagina.

{
  "type": "https://secani.com/docs/oscal/api/errors#ERR_INVALID_JSON",
  "title": "Invalid JSON",
  "status": 400,
  "code": "ERR_INVALID_JSON",
  "detail": "The submitted document is not well-formed JSON.",
  "resolution": "Send one well-formed JSON document as the request body and check commas, quotes, and brackets.",
  "documentation": "https://secani.com/docs/oscal/api/errors#ERR_INVALID_JSON"
}

Non includere mai una chiave API, un documento confidenziale completo o altri segreti in una richiesta di supporto. Registra invece lo stato, il codice stabile, le intestazioni di risposta e una riproduzione minima redatta.

Comportamento del cliente

• Trattare 400, 401, 405, 413, E 415 come problemi di richiesta che richiedono la modifica del client prima di riprovare.
• Per 429 E 503, rispetto Retry-After. Non creare un ciclo di tentativi stretto.
• Riprova 500 una volta con backoff. Se persiste, contattare Secani con il codice stabile e una riproduzione redatta.
• Un risultato di convalida con HTTP 200 E "valid": false non è un errore API. Si tratta di un report riuscito per un documento OSCAL non valido.

ERR_INVALID_JSON

Il corpo non è JSON ben formato. Invia esattamente un documento JSON, controlla virgolette e virgole e convalida il file localmente prima di riprovare.

ERR_INVALID_UTF8

Il corpo non può essere decodificato come UTF-8. Ricodifica l'origine come UTF-8 senza sostituire i byte non validi, quindi inviala di nuovo con Content-Type: application/json.

ERR_UNKNOWN_MODEL

Il JSON non contiene un modello root OSCAL riconosciuto. Utilizzare un catalogo, un profilo, una definizione dei componenti, un piano di sicurezza del sistema, un piano di valutazione, i risultati della valutazione, un POA&M o un documento del modello completo OSCAL 1.2.2.

ERR_INVALID_CONTENT_ENCODING

La richiesta dichiarata Content-Encoding: gzip, ma i byte non erano gzip validi. Invia il corpo dell'identità originale o crea un nuovo flusso gzip e mantieni l'intestazione coerente con il payload effettivo.

ERR_UNSUPPORTED_PARAMETER

Un parametro di query contiene un valore non supportato. Utilizzo level=schema O level=full, passare ID regola semantica documentati solo con level=full, e perno oscal-version A 1.2.2.

ERR_METHOD_NON_ALLOWED

L'endpoint di convalida accetta POST per la convalida e OPTIONS per il rilevamento multiorigine. Invia il documento OSCAL come corpo POST anziché utilizzare GET.

ERR_NON_TROVATO

Il percorso API v1 richiesto non è pubblicato. Inizia da Indice API oppure usa il canonico Documento OpenAPI per selezionare un punto finale.

ERR_PAYLOAD_TOO_LARGE

La richiesta non elaborata supera i 4 MB o il corpo gzip decompresso supera i 24 MB. OSCAL JSON si comprime bene: esegui il gzip del documento, mantieni il payload decompresso entro 24 MB o dividi il lavoro in singoli documenti.

ERR_UNSUPPORTED_MEDIA_TYPE

L'endpoint accetta JSON con identità o codifica gzip. Impostato Content-Type: application/json e rimuovere tipi di contenuto o codifiche di contenuto non supportati.

ERR_RATE_LIMITED

La finestra di richiesta attiva è esaurita. Aspetta Retry-After, utilizzare il RateLimit-* intestazioni per stimolare le chiamate future o creare una chiave API OSCAL monouso per limiti più elevati.

ERR_INVALID_API_KEY

La chiave al portatore fornita è sconosciuta o revocata. Sostituiscilo con un attivo sk_oscal_ chiave dalle impostazioni dell'organizzazione. Una chiave non valida presentata non ricorre mai all'accesso anonimo.

ERR_KEY_SERVICE_NON DISPONIBILE

La verifica delle credenziali o del limite di velocità è temporaneamente non disponibile, pertanto la convalida non è stata eseguita. Aspetta Retry-After e riprovare. Non spostare la chiave in una stringa di query o in un altro canale.

ERR_INTERNO

Si è verificato un errore imprevisto del server senza esporre i componenti interni. Riprovare una volta più tardi. Se il problema persiste, contattare ciao@secani.com con lo stato, il codice, l'ora e una riproduzione minima redatta.

Il toolkit condiviso Secani OSCAL definisce inoltre ERR_INVALID_XML E ERR_INVALID_YAML. L'endpoint di convalida HTTP v1 solo JSON non emette tali codici e attualmente non accetta XML o YAML.

Vedi il Guida all'API, guida ai permessi, e canonico Specifica OpenAPI.