Skip to main content

Improved Messaging for Docs as Code - Async API

· One min read

The status endpoint of the Docs as Code - Async API now provides granular error messaging that clearly distinguishes between subscription issues and validation problems, complete with actionable details for faster troubleshooting.

What has Changed?​

Previously, the response returned from the status endpoint contained a single property, which is status that indicated whether the portal generation was InProgress, Completed or had Failed. The status property now also returns:

  1. SubscriptionError: Indicates features missing from your subscription that require an upgrade.
  2. ValidationError: Indicates problems in your request or build file for easier debugging.

In addition to this, a new errors property is now included when the status is SubscriptionError or ValidationError. This property provides detailed information about the specific issue encountered.

Below are examples of each scenario.

Subscription Error​

{
    "status": "SubscriptionError",
    "errors": {
        "features": [
            "The following features are not allowed on your subscription: Callbacks, Webhooks"
        ]
    }
}

Validation Error​

{
    "status": "ValidationError",
    "errors": {
        "generatePortal.baseUrl": [
            "generatePortal.baseUrl cannot be null or empty when generatePortal.indexable is enabled."
        ]
    }
}

Additionally, the async portal generation endpoint no longer returns a 403 for subscription-related errors.