Response and HTTP Status Codes of Data Service
When you call an API endpoint defined in Data Service, Data Service returns an HTTP response. Understanding the structure of this response and the meaning of status codes is essential for interpreting data returned by a Data Service endpoint.
This document describes the response and status codes of Data Service in TiDB Cloud.
Response
Data Service returns an HTTP response with a JSON body. The response body contains the following fields:
type: string. The type of this endpoint. The value might be"sql_endpoint"or"chat2data_endpoint". Different endpoints return different types of responses.data: object. The execution results, which include three parts:columns: array. Schema information for the returned fields.rows: array. The returned results inkey:valueformat.result: object. The execution-related information of the SQL statement, including success/failure status, execution time, number of rows returned, and user configuration.
An example response is as follows:
- SQL Endpoint
- Chat2Data Endpoint
{
"type": "sql_endpoint",
"data": {
"columns": [
{
"col": "id",
"data_type": "BIGINT",
"nullable": false
},
{
"col": "type",
"data_type": "VARCHAR",
"nullable": false
}
],
"rows": [
{
"id": "20008295419",
"type": "CreateEvent"
}
],
"result": {
"code": 200,
"message": "Query OK!",
"start_ms": 1678965476709,
"end_ms": 1678965476839,
"latency": "130ms",
"row_count": 1,
"row_affect": 0,
"limit": 50
}
}
}
{
"type": "chat2data_endpoint",
"data": {
"columns": [
{
"col": "id",
"data_type": "BIGINT",
"nullable": false
},
{
"col": "type",
"data_type": "VARCHAR",
"nullable": false
}
],
"rows": [
{
"id": "20008295419",
"type": "CreateEvent"
}
],
"result": {
"code": 200,
"message": "Query OK!",
"start_ms": 1678965476709,
"end_ms": 1678965476839,
"latency": "130ms",
"row_count": 1,
"row_affect": 0,
"limit": 50
"sql": "select id,type from sample_data.github_events limit 1;",
"ai_latency": "30ms"
}
}
}
Status code
200
If the HTTP status code is 200 and the data.result.code field also shows 200, this indicated that the SQL statement is executed successfully. Otherwise, TiDB Cloud fails to execute the SQL statement defined in your endpoint. You can check the code and message fields for detailed information.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 1146,
"message": "table not found",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
400
This status code indicates that the parameter check failed.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 400,
"message": "param check failed! {detailed error}",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
401
This status code indicates that the authentication failed due to lack of permission.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 401,
"message": "auth failed",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
404
This status code indicates that the authentication failed due to the inability to find the specified endpoint.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 404,
"message": "endpoint not found",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
405
This status code indicates that the request used a method that is not allowed. Note that Data Service only supports GET and POST.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 405,
"message": "method not allowed",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
408
This status code indicates that the request exceeds the timeout duration of the endpoint. To modify the timeout of an endpoint, refer to Configure properties.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 408,
"message": "request timeout.",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
429
This status code indicates that the request exceeds the rate limit of the API key. For more quota, you can submit a request to our support team.
An example response is as follows:
- SQL Endpoint
- Chat2Data Endpoint
{
"type": "",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 49900007,
"message": "The request exceeded the limit of 100 times per apikey per minute. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
{
"type": "chat2data_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 429,
"message": "The AI request exceeded the limit of 100 times per day. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
500
This status code indicates that the request met an internal error. There might be various causes for this error.
One possible cause is that the authentication failed due to the inability to connect to the authentication server.
An example response is as follows:
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 500,
"message": "internal error! defaultPermissionHelper: rpc error: code = DeadlineExceeded desc = context deadline exceeded",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}
This might also be related to the inability to connect the TiDB Cloud cluster. You need to refer to the message for troubleshooting.
{
"type": "sql_endpoint",
"data": {
"columns": [],
"rows": [],
"result": {
"code": 500,
"message": "internal error! {detailed error}",
"start_ms": "",
"end_ms": "",
"latency": "",
"row_count": 0,
"row_affect": 0,
"limit": 0
}
}
}