Troubleshooting API documentation issues

This article is a consolidated reference for every error, warning, and unexpected behavior documented across Document360's API documentation feature. Use it to diagnose and resolve issues with imports, authentication, the Try It! feature, rendering, and the knowledge base site.

Import errors

Invalid format – API file upload failed

When it occurs: When one or more responses in your OpenAPI specification file are missing the required content section.

Why it happens: Document360 enforces strict OpenAPI validation rules. Although a file may pass validation in tools like Swagger Editor, Document360 requires all responses to explicitly define both the media type (for example, application/json) and a schema reference under a content block. Responses that are empty or that reference a schema directly without a content wrapper will cause this error.

How to fix it:

1. Open your OpenAPI spec file in a text editor or IDE.

2. Locate any response definitions that are empty or that reference a schema without a content block.

   Incorrect:

   responses:
     "200": {}

   Correct:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/YourSchema"

3. Save the file and re-upload it to Document360.

If the issue persists, contact the Document360 support team.

Invalid URL

When it occurs: When creating an API reference from a URL and the URL provided cannot be fetched or resolved.

Why it happens: The URL may be malformed, unreachable from Document360's servers, or pointing to a resource that is not a valid OpenAPI spec.

How to fix it: Verify the URL resolves correctly in a browser or with curl. Ensure it returns a valid JSON or YAML OpenAPI document. Correct the URL and try again.

Unsupported file format

When it occurs: When the uploaded file is not a supported format.

How to fix it: Ensure your file is one of the following: JSON, YAML, or YML. Document360 supports OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1, and Postman Collections.

Unable to add API reference – invalid specification file

Error message: "Unable to add API reference. This operation can't be completed. Please ensure that you have given a valid specification file."

When it occurs: When uploading a YAML specification file that has been copied or exported from a rich-text editor or word processor.

Why it happens: The uploaded YAML file is malformed and not a valid OpenAPI 3.0 YAML document. This commonly occurs when the file has been copied or exported from a rich-text editor, which introduces formatting characters such as \f0\fs24 or trailing backslashes that break the YAML format.

1. Validate your spec file: Open your YAML file in a tool like Swagger Editor or a code editor to check for errors or formatting issues.

2. Look for unwanted formatting characters: Check for characters like \f0\fs24 or trailing backslashes \ (especially in the endpoint description) that may have been introduced during copy-paste from a rich-text source. These can break the YAML format.

3. Clean up the file: Use a plain text or code editor to remove any special formatting characters. Avoid using word processors when editing or saving YAML files.

4. Re-upload the file: After cleaning the file and ensuring it’s a valid OpenAPI 3.0 YAML, try uploading it again.

Summary and tags not reflected after import

When it occurs: After importing a spec, endpoint articles display incorrect titles or appear under unexpected category folders.

Why it happens: The summary and tags fields are defined at the path level in the spec rather than inside the operation object (get, post, put, or delete). Additionally, the tags field must always be written as an array, even when only one tag is used.

How to fix it:

1. Open your OpenAPI specification file in a text editor.

2. Move the summary and tags fields inside each operation object and ensure tags is written as an array.

   Incorrect:

   /your-endpoint:
     summary: My Endpoint
     tags: My Category
     get:
       ...

   Correct:

   /your-endpoint:
     get:
       summary: My Endpoint
       tags: ["My Category"]
       ...

3. Save the file and reimport it into Document360. The imported articles will use the summary value as the article title, and tag-based folders will be created correctly.

If the issue persists, contact the Document360 support team.

Upload fails with 400 Bad Request – specification file too large

When it occurs: When uploading a valid YAML or JSON OpenAPI specification file that contains endpoints with deeply nested response schemas and multiple response codes per endpoint.

Why it happens: Although the file may be valid YAML and pass external validators such as Swagger Editor, Document360 enforces an internal article size limit. When an endpoint contains response schemas nested eight or more levels deep across multiple response codes, the resulting data size exceeds this limit and cannot be processed or stored.

How to fix it:

1. Open your OpenAPI specification file in a text editor or IDE.

2. For each endpoint, retain only one 201 response type, one 400-series response type, and the default response type. Remove all additional response codes.

3. For endpoints where the 201 response alone contains deeply nested schemas, retain only the 201 response type and remove the 400-series and default response types entirely.

4. Save the modified file and re-upload it to Document360.

NOTE

If publishing fails after a successful upload, contact the Document360 support team. Publishing may require backend assistance due to the article size limitation.

Top-level tag descriptions not rendered in API documentation

When it occurs: Descriptions and metadata defined in top-level OpenAPI tag objects are not displayed in the generated API documentation.

Why it happens: When an OpenAPI specification file contains top-level tags used to group API operations, Document360 converts those tags into folder-type categories during import. Folder categories are used only for organising endpoints and do not generate standalone content pages. As a result, any description or metadata defined within those top-level tag objects is not rendered.

Workaround: Add the relevant context directly to the individual endpoint descriptions within the tag, so the information is visible on the generated endpoint pages.

Spec configuration issues

Missing or incorrect server URL in OpenAPI spec

When it occurs: The Try It! button does not appear, or API consumers are unsure which base URL to use for their requests.

Why it happens: The servers section is missing from the OpenAPI spec or contains an incorrect URL. Without it, API users cannot determine where to send requests and documentation tools cannot populate the Try It! feature.

How to fix it:

1. Add a correct servers section to your spec:

   servers:
     - url: https://api.yourdomain.com
       description: Production

2. For region-specific APIs, define multiple server entries:

   servers:
     - url: https://api.yourdomain.com
       description: Global
     - url: https://api.us.yourdomain.com
       description: US region

3. Ensure that all API clients (for example, Postman, cURL) use the correct server URL when making requests.

NOTE

The URLs above are examples. Use the actual base URL for your API.

Empty body shown in API documentation

When it occurs: An endpoint's request body displays as empty in the published documentation.

Why it happens: The OpenAPI schema is missing "type": "object" on one or more object definitions.

How to fix it: Ensure every object definition in your OpenAPI spec includes "type": "object". This attribute tells Document360 how to render request body parameters and response schemas accurately, making it easier for developers to understand and interact with your API.

Authentication errors

403 error when using Try It!

When it occurs: Clicking Try It! on an endpoint immediately returns a 403 error after a spec has been successfully uploaded.

Why it happens: The spec is missing a definition for the BearerAuth security mechanism under components/securitySchemes.

How to fix it:

1. Check your spec for a BearerAuth security scheme definition under components/securitySchemes.

2. If it is missing, add it:

   components:
     securitySchemes:
       BearerAuth:
         type: http
         scheme: bearer

3. Re-upload the spec.

4. During import, check the Alerts section for any warnings related to Bearer Authentication and address them.

   

401 Unauthorized error from incorrect server URL

When it occurs: API requests return a 401 Unauthorized response when using Try It! or when making direct API calls.

Why it happens: The wrong region-based server URL is being used. For example, sending a request to https://api.yourdomain.com when the correct endpoint is https://api.us.yourdomain.com will cause authentication failures because the region-specific endpoint validates credentials differently.

How to fix it:

1. Confirm you are using the correct region-based URL for your account.

2. Ensure the correct client ID and client secret are being used with that URL.

3. Verify the authentication token is correctly included in the request header.

Access and permission errors

400 error – API access is disabled

Error message: "400 error – API access is disabled. Please contact your project administrator."

When it occurs: When attempting to use the public API and public API access has been deactivated in the project settings.

How to fix it:

1. Navigate to Settings () > AI settings > Eddy AI settings in the Knowledge base portal.

2. Under the AI search suite section, ensure that the Public API checkbox is selected.

   

3. If the issue persists, contact the Document360 support team.

403 error when posting via API endpoint

When it occurs: When attempting a POST request through the API endpoint and receiving a 403 response.

Why it happens: The API token being used does not have the required permissions to make POST requests.

How to fix it: Review the permissions assigned to your API token. Ensure it has write and POST permissions enabled. Update the token settings and retry.

Rendering and display issues

Incorrect HTML styling in API response

When it occurs: When retrieving article HTML content via the API, the rendered output displays with broken styling or misplaced quotes.

Why it happens: API responses are formatted in JSON, which uses escape characters (for example, \") to handle certain characters safely. If these escaped characters are not converted back (unescaped) before rendering, the HTML structure breaks.

For example, a paragraph like:

<p>This is a "sample" paragraph.</p>

May appear in the JSON response as:

"<p>This is a \"sample\" paragraph.</p>"

How to fix it:

1. Retrieve the HTML content via the API and inspect the response.

2. Look for escaped characters in the JSON response, such as:

   • \" (escaped double quotes)

   • \\ (escaped backslashes)

   • \n (newline)

   • \t (tab)

3. Unescape the JSON content before rendering it. This restores the original HTML structure.

4. Verify the styling after unescaping to ensure the content appears correctly.

5. If the issue persists, check if additional modifications in your code are altering the API response.

   

   Once unescaped properly, the HTML will display as expected, preventing styling discrepancies.

Variables and snippets not rendering in API response

When it occurs: When retrieving article content via the API, variables appear as unprocessed placeholders — for example, {{variable.UserName}} instead of the actual value.

Why it happens: The isForDisplay parameter is not set correctly in the API request.

• When isForDisplay = true: variables and snippets are fully rendered in the response, and placeholders are replaced with actual values.

• When isForDisplay = false (or not set): the response contains unprocessed placeholders, which are not suitable for direct display.

How to fix it:

1. Retrieve the article content via the API and inspect the response.

2. Check if variables or snippets appear unprocessed in the response.

3. Ensure the API request includes "isForDisplay": true. Example request:

   {
     "articleId": "your-article-id",
     "isForDisplay": true
   }

4. Send the modified request and verify the API response now displays correctly rendered variables and snippets.

5. If the issue persists, ensure that the system processing the API response handles and displays the rendered content properly.

IMPORTANT

When updating articles via the API, do not pass fully rendered content back. This would replace dynamic placeholders with static values, breaking future rendering.

Category and navigation issues

Nested categories not displaying correctly

When it occurs: Endpoints that should appear in nested subcategories are not organised hierarchically after import.

How it works: Document360 supports second-level subcategories using the > symbol in OpenAPI tags. For example, a tag of Pets > Details will create a Pets category with a Details subcategory inside it. This structure is preserved during resync operations.

tags:
  - name: "Pets > Details"

NOTE

The API documentation workspace supports a maximum of three levels of subcategories. If your spec includes more than three levels, any additional levels are placed at the third level.

Category order is not what I expected

When it occurs: After uploading a spec, categories appear in a different order than expected.

Why it happens: Categories in Document360 are created based on the tag order defined in the spec file. The order of tags in your spec determines the order categories appear in the documentation.

How to fix it: Reorder the tags array in your OpenAPI spec to match the desired category order, then resync.

Knowledge base site errors

Knowledge base homepage redirects to /apidocs (page not found)

When it occurs: After an account upgrade, visiting the knowledge base homepage automatically redirects to /apidocs, which returns a 404 or blank page.

Why it happens: When an account is upgraded, the API documentation workspace may be set to Public reader access. This causes the knowledge base homepage to redirect visitors to /apidocs, which does not exist by default.

How to fix it:

1. Navigate to Settings () > Users & Permissions in the left navigation bar of the Knowledge base portal.

2. In the left navigation pane, go to Reader access.

3. Locate the API documentation workspace.

4. Set Reader access to Private.

   

This will stop the unintended redirect and restore normal access to your knowledge base homepage.

Still having issues?

If the steps above do not resolve your issue, contact the Document360 support team directly.