API error recovery

The Secani OSCAL Validation API returns errors as RFC 9457 problem details with the media type application/problem+json. A client can branch on the stable code, show title and detail to a person, and follow resolution without parsing prose. The type and documentation fields point back to the corresponding entry on this 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"
}

Never include an API key, full confidential document, or other secret in a support request. Record the status, stable code, response headers, and a minimal redacted reproduction instead.

Client behavior

• Treat 400, 401, 405, 413, and 415 as request problems that require a client change before retrying.
• For 429 and 503, respect Retry-After. Do not create a tight retry loop.
• Retry 500 once with backoff. If it persists, contact Secani with the stable code and a redacted reproduction.
• A validation result with HTTP 200 and "valid": false is not an API error. It is a successful report for an invalid OSCAL document.

ERR_INVALID_JSON

The body is not well-formed JSON. Send exactly one JSON document, check quoting and commas, and validate the file locally before retrying.

ERR_INVALID_UTF8

The body cannot be decoded as UTF-8. Re-encode the source as UTF-8 without replacing invalid bytes, then submit it again with Content-Type: application/json.

ERR_UNKNOWN_MODEL

The JSON does not contain one recognized OSCAL root model. Use an OSCAL 1.2.2 catalog, profile, component definition, system security plan, assessment plan, assessment results, POA&M, or complete model document.

ERR_INVALID_CONTENT_ENCODING

The request declared Content-Encoding: gzip, but the bytes were not valid gzip. Send the original identity body or create a fresh gzip stream and keep the header consistent with the actual payload.

ERR_UNSUPPORTED_PARAMETER

A query parameter contains an unsupported value. Use level=schema or level=full, pass documented semantic rule IDs only with level=full, and pin oscal-version to 1.2.2.

ERR_METHOD_NOT_ALLOWED

The validation endpoint accepts POST for validation and OPTIONS for cross-origin discovery. Send the OSCAL document as the POST body rather than using GET.

ERR_NOT_FOUND

The requested v1 API path is not published. Start at the API index or use the canonical OpenAPI document to select an endpoint.

ERR_PAYLOAD_TOO_LARGE

The raw request exceeds 4 MB or the decompressed gzip body exceeds 24 MB. OSCAL JSON compresses well: gzip the document, keep the decompressed payload within 24 MB, or split work into individual documents.

ERR_UNSUPPORTED_MEDIA_TYPE

The endpoint accepts JSON with identity or gzip encoding. Set Content-Type: application/json and remove unsupported content types or content encodings.

ERR_RATE_LIMITED

The active request window is exhausted. Wait for Retry-After, use the RateLimit-* headers to pace future calls, or create a single-purpose OSCAL API key for higher limits.

ERR_INVALID_API_KEY

The supplied bearer key is unknown or revoked. Replace it with an active sk_oscal_ key from organization settings. A presented invalid key never falls back to anonymous access.

ERR_KEY_SERVICE_UNAVAILABLE

Credential or rate-limit verification is temporarily unavailable, so validation did not run. Wait for Retry-After and retry. Do not move the key into a query string or another channel.

ERR_INTERNAL

An unexpected server error occurred without exposing internals. Retry once later. If it persists, contact hello@secani.com with the status, code, time, and a redacted minimal reproduction.

The shared Secani OSCAL toolkit also defines ERR_INVALID_XML and ERR_INVALID_YAML. The JSON-only v1 HTTP validation endpoint does not emit those codes and does not currently accept XML or YAML.

See the API guide, permissions guide, and canonical OpenAPI specification.