Errors and Warnings

This page describes how SQL errors and warnings are returned by the REST API.

Overview

When you execute SQL queries via the REST API, the response may include errors or warnings. These are returned in a standardized format to help you identify problems and take corrective action.

Warnings

If a request completes successfully but one or more SQL warnings are raised during the execution, the API will include these warnings in the HTTP response headers.

Header Name

SQL warnings

Format

All warnings are included in the SQL warnings header, enclosed in quotation marks (") and separated by semicolons (;).

Example

BASH

HTTP/1.1 200 OK
Content-Type: application/json
SQL warnings: "First warning.";"Second warning."

Even if the query returns successfully, warnings provide valuable insights that can help you understand potential issues or areas for improvement.

SQL warnings in response headers are available since v4.10

Errors

If an error occurs that prevents the query from executing successfully, the API returns an HTTP error status code along with a JSON-formatted response body describing the issue.

JSON Response Body Fields

title: A short summary of the error.
description: A more detailed explanation of what went wrong.
hint (optional): Suggestions on how the issue might be resolved. If no hint is available, this field will equal to null.

Example

XML

GET <http://<cdatavirtuality-server-address>>:8080/rest/api/source/wrong_name

Response (application/json):

JSON

STATUS 404

{
  "title": "Something is wrong",
  "description": "Schema 'wrong_name' doesn't exist.",
  "hint": null
}

In this case, the error indicates that the requested schema could not be found, likely due to a typo or incorrect schema name in the SQL query. Correct the schema name and re-run the request.

Handling Errors and Warnings

Warnings: Check the SQL warnings header after a successful response. While the request succeeded, you may need to adjust your queries, configuration, or data sources to prevent these warnings in the future.

Errors: Review the returned JSON body for a detailed explanation. Update your request parameters, the SQL query, or the underlying data source configuration as recommended by the description and hint fields.