Odzyskiwanie błędów API

Interfejs Secani OSCAL Validation API zwraca błędy jako szczegóły problemu zgodne z RFC 9457, z typem nośnika application/problem+json. Klient może podejmować decyzje na podstawie stabilnego pola code, wyświetlać użytkownikowi title i detail oraz korzystać z pola resolution bez analizowania tekstu komunikatu. Pola type i documentation prowadzą do odpowiedniego wpisu na tej stronie.

{
  "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"
}

Nigdy nie dołączaj klucza API, całkowicie poufnego dokumentu ani innego sekretu do zgłoszenia serwisowego. Zamiast tego zapisz status, stabilny kod, nagłówki odpowiedzi i minimalną zredagowaną reprodukcję.

Zachowanie klienta

• Traktować 400, 401, 405, 413, I 415 jako problemy związane z żądaniami, które wymagają zmiany klienta przed ponowną próbą.
• Dla 429 I 503, szacunek Retry-After. Nie twórz ścisłej pętli ponawiania prób.
• Spróbować ponownie 500 raz z odliczeniem. Jeśli problem będzie się powtarzał, skontaktuj się z Secani, przekazując stabilny kod i poprawioną reprodukcję.
• Wynik weryfikacji za pomocą protokołu HTTP 200 I "valid": false nie jest błędem API. Jest to pomyślny raport dotyczący nieprawidłowego dokumentu OSCAL.

ERR_INVALID_JSON

Treść nie jest dobrze uformowana w formacie JSON. Wyślij dokładnie jeden dokument JSON, sprawdź cudzysłowy i przecinki oraz zweryfikuj plik lokalnie przed ponowną próbą.

ERR_INVALID_UTF8

Treści nie można zdekodować w formacie UTF-8. Zakoduj ponownie źródło jako UTF-8 bez zastępowania nieprawidłowych bajtów, a następnie prześlij je ponownie za pomocą Content-Type: application/json.

ERR_UNKNOWN_MODEL

JSON nie zawiera jednego rozpoznanego modelu głównego OSCAL. Skorzystaj z katalogu, profilu, definicji komponentów OSCAL 1.2.2, planu bezpieczeństwa systemu, planu oceny, wyników oceny, POA&M lub kompletnego dokumentu modelowego.

ERR_INVALID_CONTENT_ENCODING

Zgłoszono żądanie Content-Encoding: gzip, ale bajty nie były prawidłowym plikiem gzip. Wyślij oryginalną treść tożsamości lub utwórz nowy strumień gzip i zachowaj spójność nagłówka z rzeczywistym ładunkiem.

ERR_UNSUPPORTED_PARAMETER

Parametr zapytania zawiera nieobsługiwaną wartość. Używać level=schema Lub level=full, przekazuj udokumentowane identyfikatory reguł semantycznych tylko za pomocą level=full, i przypnij oscal-version Do 1.2.2.

ERR_METHOD_NOT_ALLOWED

Punkt końcowy walidacji akceptuje POST do sprawdzenia i OPTIONS do odkrywania między źródłami. Wyślij dokument OSCAL jako treść POST, zamiast używać GET.

ERR_NOT_FOUND

Żądana ścieżka API wersji 1 nie została opublikowana. Zacznij od Indeks API lub użyj kanonicznego Dokument OpenAPI aby wybrać punkt końcowy.

ERR_PAYLOAD_TOO_LARGE

Rozmiar nieprzetworzonego żądania przekracza 4 MB lub treść zdekompresowanego pliku gzip przekracza 24 MB. OSCAL JSON dobrze kompresuje: spakuj dokument gzipem, przechowuj zdekompresowany ładunek w granicach 24 MB lub podziel pracę na poszczególne dokumenty.

ERR_UNSUPPORTED_MEDIA_TYPE

Punkt końcowy akceptuje JSON z kodowaniem tożsamości lub gzip. Ustawić Content-Type: application/json i usuń nieobsługiwane typy zawartości lub kodowanie treści.

ERR_RATE_LIMITED

Aktywne okno żądania zostało wyczerpane. Czekać na Retry-After, użyj RateLimit-* nagłówki, aby sterować przyszłymi połączeniami, lub utwórz uniwersalny klucz API OSCAL dla wyższych limitów.

ERR_INVALID_API_KEY

Dostarczony klucz na okaziciela jest nieznany lub unieważniony. Zamień go na aktywny sk_oscal_ klucz z ustawień organizacji. Przedstawiony nieprawidłowy klucz nigdy nie zapewnia dostępu anonimowego.

ERR_KEY_SERVICE_UNAVAILABLE

Weryfikacja danych uwierzytelniających lub limitu szybkości jest tymczasowo niedostępna, dlatego weryfikacja nie została przeprowadzona. Czekać na Retry-After i spróbuj ponownie. Nie przenoś klucza do ciągu zapytania lub innego kanału.

BŁĄD_INTERNAL

Wystąpił nieoczekiwany błąd serwera bez ujawnienia elementów wewnętrznych. Spróbuj ponownie później. Jeśli będzie się powtarzać, skontaktuj się hello@secani.com ze statusem, kodem, czasem i zredagowaną minimalną reprodukcją.

Udostępniony zestaw narzędzi Secani OSCAL również definiuje ERR_INVALID_XML I ERR_INVALID_YAML. Punkt końcowy weryfikacji HTTP w wersji 1 obsługujący tylko JSON nie emituje tych kodów i obecnie nie akceptuje formatów XML ani YAML.

Zobacz Przewodnik po API, przewodnik po uprawnieniach, i kanoniczne Specyfikacja OpenAPI.