Skip to main content

Docs as Code Updates: LF Line Endings, Better Errors

· 2 min read

We’ve upgraded the underlying infrastructure of our Docs as Code API to improve its performance. We've also shipped several improvements related to error messages to streamline your CI/CD pipelines and make troubleshooting easier. Below you’ll find a quick overview of what’s changed and how to adapt your integrations.

Line Endings​

We now standardize on LF (\n) for all generated files inside the ZIP archive.

  • What changed

    • Previously, output files used CRLF (\r\n).
    • Going forward, every file will end with Unix-style LF only.

  • Action required

    • Ensure your scripts or diff tools expect LF endings.

TOC File Path Handling​

We tightened path validations to avoid cross-platform inconsistencies.

  • Case sensitivity

    • All file path references in your TOC files are now case-sensitive.
    • docs/Getting-Started.md ≠ docs/getting-started.md.

  • Separator enforcement

    • Only forward slashes (/) are allowed.

       # Valid TOC entry
       - page: Getting Started
         file: docs/getting-started.md

Error Handling Changes​

We now return more precise HTTP status codes and structured JSON bodies for common failure scenarios.

400 Bad Request​

Returned on input validation failures

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "One or more validation failures have occurred",
  "instance": "/api/portal/v2",
  "errors": {
    "": [
      "Build file not found"
    ]
  }
}

401 Unauthorized​

Returned when authentication credentials are missing or invalid.

{
  "message": "Authorization has been denied for this request."
}

403 Forbidden​

Returned when the request is authenticated but lacks feature access.

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3",
  "title": "Access denied to resource.",
  "status": 403,
  "detail": "Requested features are not available in subscription",
  "instance": "/api/portal",
  "errors": {
    "": [
      "Unsupported languages provided in build file 'CS_NET_STANDARD_LIB'"
    ]
  }
}

422 Unprocessable Entity​

Returned for build-time errors in your spec or TOC. The response includes an error.zip archive which contains an error report.