API-Fehler beheben
Stabile Fehlercodes der Secani OSCAL Validierungs-API, RFC-9457-Felder und sichere Schritte zur Fehlerbehebung.
Die Secani OSCAL Validierungs-API liefert Fehler als RFC-9457-Problem-Details mit dem Medientyp application/problem+json. Clients können auf dem stabilen Feld code verzweigen, title und detail anzeigen und den konkreten Hinweis in resolution befolgen. type und documentation verweisen auf den passenden Abschnitt dieser Seite.
Ein Ergebnis mit HTTP 200 und "valid": false ist kein API-Fehler, sondern ein erfolgreich erzeugter Bericht für ein ungültiges OSCAL-Dokument. Bei 429 und 503 muss ein Client Retry-After beachten. Zugangsschlüssel, vertrauliche Dokumente und andere Geheimnisse gehören nie in Support-Anfragen.
ERR_INVALID_JSON
Sende genau ein wohlgeformtes JSON-Dokument und prüfe Anführungszeichen, Kommata und Klammern vor dem erneuten Versuch.
ERR_INVALID_UTF8
Kodiere den Request-Body als gültiges UTF-8 und sende ihn erneut mit Content-Type: application/json.
ERR_UNKNOWN_MODEL
Verwende eines der acht unterstützten OSCAL-1.2.2-Wurzelmodelle, beispielsweise Catalog, Profile oder System Security Plan.
ERR_INVALID_CONTENT_ENCODING
Sende einen unkomprimierten Body oder gültige gzip-Bytes und stelle sicher, dass Content-Encoding zum tatsächlichen Body passt.
ERR_UNSUPPORTED_PARAMETER
Verwende level=schema oder level=full, dokumentierte Regel-IDs nur zusammen mit level=full und oscal-version=1.2.2.
ERR_METHOD_NOT_ALLOWED
Sende das OSCAL-Dokument per POST. OPTIONS steht für CORS-Erkennung zur Verfügung; GET validiert keine Dokumente.
ERR_NOT_FOUND
Der angeforderte v1-Pfad ist nicht veröffentlicht. Beginne beim API-Index oder bei der OpenAPI-Spezifikation.
ERR_PAYLOAD_TOO_LARGE
Halte den unkomprimierten Body unter 4 MB oder sende gzip mit höchstens 24 MB dekomprimierter Größe.
ERR_UNSUPPORTED_MEDIA_TYPE
Setze Content-Type: application/json und nutze ausschließlich identity oder gzip als Content-Encoding.
ERR_RATE_LIMITED
Warte die Dauer aus Retry-After, takte weitere Requests anhand der RateLimit-*-Header oder erstelle einen zweckgebundenen OSCAL-API-Schlüssel für höhere Limits.
ERR_INVALID_API_KEY
Ersetze den unbekannten oder widerrufenen Schlüssel durch einen aktiven sk_oscal_-Schlüssel aus den Organisationseinstellungen.
ERR_KEY_SERVICE_UNAVAILABLE
Die Schlüssel- oder Rate-Limit-Prüfung ist vorübergehend nicht erreichbar. Warte Retry-After ab und versuche es erneut.
ERR_INTERNAL
Versuche es später einmal erneut. Bleibt der Fehler bestehen, sende Status, Code, Zeitpunkt und eine redigierte Minimalreproduktion an hello@secani.com.
Die gemeinsamen Secani-OSCAL-Bibliotheken kennen zusätzlich ERR_INVALID_XML und ERR_INVALID_YAML. Der JSON-only-v1-HTTP-Endpunkt gibt diese Codes nicht aus und akzeptiert derzeit weder XML noch YAML.
Siehe auch API-Dokumentation, Berechtigungen und OpenAPI-Spezifikation.