Récupération d'erreur API

L'API de validation Secani OSCAL renvoie des erreurs sous forme de détails du problème RFC 9457 avec le type de média application/problem+json. Un client peut créer un branchement sur la stable code, montrer title et detail à une personne, et suivez resolution sans analyser la prose. Le type et documentation les champs renvoient à l’entrée correspondante sur cette page.

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

N'incluez jamais de clé API, de document entièrement confidentiel ou tout autre secret dans une demande d'assistance. Enregistrez plutôt le statut, le code stable, les en-têtes de réponse et une reproduction minimale expurgée.

Comportement des clients

• Traiter 400, 401, 405, 413, et 415 comme problèmes de demande qui nécessitent un changement de client avant de réessayer.
• Pour 429 et 503, respect Retry-After. Ne créez pas une boucle de nouvelle tentative serrée.
• Réessayer 500 une fois avec recul. Si cela persiste, contactez Secani avec le code stable et une reproduction expurgée.
• Un résultat de validation avec HTTP 200 et "valid": false n'est pas une erreur API. Il s'agit d'un rapport réussi pour un document OSCAL non valide.

ERR_INVALID_JSON

Le corps n'est pas un JSON bien formé. Envoyez exactement un document JSON, vérifiez les guillemets et les virgules, et validez le fichier localement avant de réessayer.

ERR_INVALID_UTF8

Le corps ne peut pas être décodé en UTF-8. Ré-encodez la source en UTF-8 sans remplacer les octets invalides, puis soumettez-la à nouveau avec Content-Type: application/json.

ERR_UNKNOWN_MODEL

Le JSON ne contient pas de modèle racine OSCAL reconnu. Utilisez un catalogue OSCAL 1.2.2, un profil, une définition de composant, un plan de sécurité du système, un plan d'évaluation, des résultats d'évaluation, un POA&M ou un document modèle complet.

ERR_INVALID_CONTENT_ENCODING

La demande déclarée Content-Encoding: gzip, mais les octets n'étaient pas un gzip valide. Envoyez le corps de l'identité d'origine ou créez un nouveau flux gzip et gardez l'en-tête cohérent avec la charge utile réelle.

ERR_UNSUPPORTED_PARAMETER

Un paramètre de requête contient une valeur non prise en charge. Utiliser level=schema ou level=full, transmettre les ID de règle sémantique documentés uniquement avec level=full, et une épingle oscal-version à 1.2.2.

ERR_METHOD_NOT_ALLOWED

Le point de terminaison de validation accepte POST pour validation et OPTIONS pour la découverte d’origines croisées. Envoyez le document OSCAL en tant que corps POST plutôt que d'utiliser GET.

ERR_NOT_FOUND

Le chemin de l'API v1 demandé n'est pas publié. Commencez par le Index des API ou utilisez le canonique Document OpenAPI pour sélectionner un point de terminaison.

ERR_PAYLOAD_TOO_LARGE

La requête brute dépasse 4 Mo ou le corps gzip décompressé dépasse 24 Mo. OSCAL JSON se compresse bien : compressez le document, conservez la charge utile décompressée dans les 24 Mo ou divisez le travail en documents individuels.

ERR_UNSUPPORTED_MEDIA_TYPE

Le point de terminaison accepte JSON avec encodage d’identité ou gzip. Ensemble Content-Type: application/json et supprimez les types de contenu ou les encodages de contenu non pris en charge.

ERR_RATE_LIMITED

La fenêtre de demande active est épuisée. Attendre Retry-After, utiliser le RateLimit-* en-têtes pour rythmer les appels futurs, ou créer une clé API OSCAL à usage unique pour des limites plus élevées.

ERR_INVALID_API_KEY

La clé du porteur fournie est inconnue ou révoquée. Remplacez-le par un actif sk_oscal_ clé à partir des paramètres de l’organisation. Une clé invalide présentée ne revient jamais à un accès anonyme.

ERR_KEY_SERVICE_UNAVAILABLE

La vérification des informations d'identification ou de la limite de débit est temporairement indisponible, la validation n'a donc pas été exécutée. Attendre Retry-After et réessayez. Ne déplacez pas la clé dans une chaîne de requête ou un autre canal.

ERR_INTERNAL

Une erreur de serveur inattendue s'est produite sans exposer les composants internes. Réessayez une fois plus tard. Si cela persiste, contactez bonjour@secani.com avec le statut, le code, l'heure et une reproduction minimale expurgée.

La boîte à outils partagée Secani OSCAL définit également ERR_INVALID_XML et ERR_INVALID_YAML. Le point de terminaison de validation HTTP JSON uniquement v1 n'émet pas ces codes et n'accepte actuellement pas XML ou YAML.

Voir le Guide des API, guide des autorisations, et canonique Spécification OpenAPI.