Recuperación de errores de API
Códigos de error estables de la API de validación OSCAL de Secani, campos de respuesta RFC 9457 y pasos de recuperación seguros para clientes y agentes.
La API de validación OSCAL de Secani devuelve errores como detalles del problema RFC 9457 con el tipo de medio application/problem+json. Un cliente puede ramificarse en el establo. code, espectáculo title y detail a una persona, y seguir resolution sin analizar la prosa. El type y documentation Los campos apuntan a la entrada correspondiente en esta página.
{
"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"
}Nunca incluya una clave API, un documento confidencial completo u otro secreto en una solicitud de soporte. En su lugar, registre el estado, el código estable, los encabezados de respuesta y una reproducción mínima redactada.
Comportamiento del cliente
- Tratar
400,401,405,413, y415como problemas de solicitud que requieren un cambio de cliente antes de volver a intentarlo. - Para
429y503, respetoRetry-After. No cree un ciclo de reintento estrecho. - Rever
500una vez con retroceso. Si persiste, comuníquese con Secani con el código estable y una reproducción redactada. - Un resultado de validación con HTTP
200y"valid": falseno es un error de API. Es un informe exitoso para un documento OSCAL no válido.
ERR_INVALID_JSON
El cuerpo no es JSON bien formado. Envíe exactamente un documento JSON, verifique las comillas y las comas y valide el archivo localmente antes de volver a intentarlo.
ERR_INVALID_UTF8
El cuerpo no se puede decodificar como UTF-8. Vuelva a codificar la fuente como UTF-8 sin reemplazar los bytes no válidos, luego envíela nuevamente con Content-Type: application/json.
ERR_UNKNOWN_MODEL
El JSON no contiene un modelo raíz OSCAL reconocido. Utilice un catálogo, perfil, definición de componentes, plan de seguridad del sistema, plan de evaluación, resultados de evaluación, POA&M o documento modelo completo de OSCAL 1.2.2.
ERR_INVALID_CONTENT_ENCODING
La solicitud declarada Content-Encoding: gzip, pero los bytes no eran gzip válidos. Envíe el cuerpo de identidad original o cree una secuencia gzip nueva y mantenga el encabezado coherente con la carga útil real.
ERR_UNSUPPORTED_PARAMETER
Un parámetro de consulta contiene un valor no admitido. Usar level=schema o level=full, pasar ID de reglas semánticas documentadas solo con level=full, y alfiler oscal-version a 1.2.2.
ERR_METHOD_NOT_ALLOWED
El punto final de validación acepta POST para validación y OPTIONS para el descubrimiento de orígenes cruzados. Envíe el documento OSCAL como cuerpo POST en lugar de utilizar GET.
ERR_NOT_ENCONTRADO
La ruta de API v1 solicitada no está publicada. Comience en el índice API o usar el canónico Documento OpenAPI para seleccionar un punto final.
ERR_PAYLOAD_TOO_LARGE
La solicitud sin formato supera los 4 MB o el cuerpo gzip descomprimido supera los 24 MB. OSCAL JSON se comprime bien: comprima el documento con gzip, mantenga la carga útil descomprimida dentro de los 24 MB o divida el trabajo en documentos individuales.
ERR_UNSUPPORTED_MEDIA_TYPE
El punto final acepta JSON con identidad o codificación gzip. Colocar Content-Type: application/json y eliminar tipos de contenido o codificaciones de contenido no compatibles.
ERR_RATE_LIMITED
La ventana de solicitud activa está agotada. Esperar Retry-After, utilizar el RateLimit-* encabezados para controlar llamadas futuras o crear una clave API OSCAL de propósito único para límites más altos.
ERR_INVALID_API_KEY
La clave al portador proporcionada es desconocida o está revocada. Reemplácelo con un activo sk_oscal_ clave desde la configuración de la organización. Una clave no válida presentada nunca recurre al acceso anónimo.
ERR_KEY_SERVICE_UNAVAILABLE
La verificación de credenciales o de límite de velocidad no está disponible temporalmente, por lo que no se ejecutó la validación. Esperar Retry-After y vuelva a intentarlo. No mueva la clave a una cadena de consulta ni a otro canal.
ERR_INTERNO
Se produjo un error inesperado en el servidor sin exponer las partes internas. Vuelva a intentarlo una vez más tarde. Si persiste, contacta hola@secani.com con el estado, código, hora y una reproducción mínima redactada.
El kit de herramientas compartido de Secani OSCAL también define ERR_INVALID_XML y ERR_INVALID_YAML. El punto final de validación HTTP v1 solo JSON no emite esos códigos y actualmente no acepta XML ni YAML.
Consulta la guía de la API, la guía de permisos y la especificación OpenAPI canónica.