Explanation of API Status Codes and Error Codes
This document lists all status and error messages that may be returned by the POST /serp/v1/request endpoint, helping you quickly identify and troubleshoot issues when calling the API.
1. General Rules
Request path
POST /serp/v1/request
HTTP status code
Both business success and business failure return HTTP 200. Use the code field in the response body to determine the result.
Request Content-Type
Only application/x-www-form-urlencoded is supported.
Authentication
Request header: Authorization: Bearer <api_key>
1.1 Response Format
All responses use a unified JSON structure:
Success (isjson=1)
{"data":{"task_id":"...","result":...},"code":0}
Success (isjson≠1)
{"task_id":"...","data":...,"code":0}
Failure
{"data":"<error description>","code":<non-zero error code>} (task_id is not returned)
Judgment rule:
code == 0means success. Any other value means failure. Thedatafield contains a human-readable error description.
2. Error Code Overview
0
Success
-
400
Request parameter error / data collection pipeline returned an error
The caller must fix the request.
401
Authentication failed
API Key issue
429
Request rate limit exceeded
Rate limiting
504
Data collection service timeout
Temporary server-side issue; retry is allowed.
Other
Downstream data collection service passthrough error
Check the specific data content.
3. Error Code Details
3.1 code: 401 - Authentication Failed
Returned when the API Key is missing, malformed, expired, or invalid.
data message
Meaning
Suggested action
apikey is empty!
The request does not include the Authorization header.
Check whether the request header contains Authorization: Bearer <api_key>.
API key authentication failed：error-1
The Authorization header format is incorrect. It does not use the Bearer <token> format.
Change it to Authorization: Bearer <api_key>.
API key authentication failed：error-2
The API Key after Bearer is empty.
Enter a valid API Key after Bearer.
API key authentication failed：error-3
The authentication service is temporarily unavailable (cached as a failed state).
Retry later. If the issue persists, contact support.
API key authentication failed：error-4
The authentication service request failed.
Retry later. If the issue persists, contact support.
API key authentication failed：error-5
The authentication service response is abnormal.
Retry later. If the issue persists, contact support.
API key authentication failed：error-6
The API Key is invalid (does not exist or has been disabled).
Check in the user center whether the API Key is correct and whether it has been disabled.
Your API key has expired and is no longer valid.
The API Key has expired.
Renew your plan or replace it with a new API Key.
3.2 code: 429 - Request Rate Limit Exceeded
data message
Meaning
Suggested action
Too Many Requests
The request rate exceeds the plan limit (default: 10 requests per second; high-concurrency plans follow the purchased limit).
Reduce concurrent request frequency or upgrade to a higher-QPS plan.
3.3 code: 400 - Request Format Error
Returned when the request body format is invalid.
data message
Meaning
Suggested action
JSON not supported!Please use form data!
The request incorrectly uses application/json as the Content-Type.
Submit the request as application/x-www-form-urlencoded.
Failed to parse form data!
Failed to parse the form data.
Check whether the request body is valid x-www-form-urlencoded data.
Bad Request!
The request Content-Type is not supported, such as multipart/form-data.
Use application/x-www-form-urlencoded.
3.4 code: 400 - Parameter Validation Failed
Returned when required parameters are missing, parameter formats are invalid, or mutually exclusive parameters are provided together.
Common Parameters
data message
Trigger condition
Suggested action
Missing query `q` parameter
q is missing when engine is google, bing, or duckduckgo.
Add the query keyword parameter q.
Missing query `text` parameter
text is missing when engine=yandex.
Add the query keyword parameter text.
Invalid url format
When engine=google_lens, url is neither a valid http(s) URL nor a valid base64 image.
Use a valid image URL or base64 image string.
Invalid tbm parameter!
When engine=google, the tbm value is not in the supported list.
Refer to the engine documentation and use a supported tbm value.
Google Images
data message
Trigger condition
Suggested action
'period_unit'/'period_value' parameters can't be used with 'start_date'/'end_date' parameters.
Time range parameters conflict.
Choose one: use period_unit/period_value, or use start_date/end_date.
Google News
The following parameters are mutually exclusive. Passing any two of them together will cause an error:
data message
Suggested action
topic_token, publication_token, and story_token parameters can't be used together.
Only one of the three can be provided.
publication_token and story_token parameters can't be used together.
Choose one.
story_token and section_token parameters can't be used together.
Choose one.
topic_token and story_token parameters can't be used together.
Choose one.
topic_token and so parameters can't be used together.
Choose one.
Google Product
data message
Trigger condition
Suggested action
Missing query `product_id` parameter
product_id is missing.
Add product_id.
`product_id` is too short (minimum is 8 characters)
product_id is shorter than 8 characters.
Use a complete product_id (at least 8 characters).
`product_id` query parameter cannot contain special characters
product_id contains special characters.
Use only valid characters.
offers, specs, and reviews parameters can't be used together
offers, specs, and reviews are provided together.
Choose one of the three.
Google Flights
data message
Trigger condition
Suggested action
Missing query `departure_id` parameter
Departure location is missing.
Add departure_id.
Missing query `arrival_id` parameter
Destination is missing.
Add arrival_id.
3.5 code: 400 - URL, Region, and Account Validation
data message
Meaning
Suggested action
url is invalid!: <specific reason>
URL assembly or validation failed. Common reasons include url is required, invalid url format: ..., and invalid base URL: ....
Check whether the provided URL is valid and whether it uses a supported engine domain.
url is invalid!
The URL domain rule validation failed.
Confirm whether the target domain is within the supported range.
Not supported for use in mainland China:<ClientIP>
The caller IP is from mainland China and is not on the whitelist.
Use an overseas IP, or contact support to apply for whitelist access.
Package has expired!
The plan has expired or the available balance is less than or equal to 0.
Renew or upgrade your plan.
3.6 code: 504 - Data Collection Service Timeout
data message
Meaning
Suggested action
Data collection API request timeout!
The downstream data collection service has a network issue or timed out.
Retry later. If the issue persists, contact support.
3.7 code: 400 - Data Collection Pipeline Error
Used when the request parameters are valid, but the data collection execution pipeline returns an error.
data message
Meaning
Suggested action
Parameter error
Failed to construct the data collection request, usually due to URL parsing failure.
Check whether the input parameters are valid. You may retry once.
The data collection API returned incorrect parameters!
The data collection service returned an unrecognized result.
Retry later. If the issue persists, contact support.
Internal parsing error
Failed to parse the inner data collection result.
Retry later. If the issue persists, contact support.
json value is not valid
The json parameter value is invalid. Only 1, 2, 3, and 5 are supported.
Change it to a supported value.
JSON data retrieval failed
Failed to retrieve JSON data from the collection result.
Retry later.
HTML data retrieval failed
Failed to retrieve HTML data from the collection result.
Retry later.
HTML fetch failed: ... / JSON fetch failed: ...
When json=2, concurrent HTML and JSON retrieval failed. Multiple errors may be concatenated.
Retry later.
3.8 Other code - Downstream Passthrough Error
When the downstream data collection service returns a non-200 status, this API passes through its code and error description as-is.
code
Status code returned by the downstream data collection service.
data
Original error description returned by the downstream data collection service.
The specific meaning of this type of error depends on the downstream data collection service response. If the issue cannot be resolved for a long time, contact support and provide the full response content.
4. Response Examples
4.1 Success
4.2 Parameter Error
4.3 Authentication Failed
4.4 API Key Expired
4.5 Rate Limited
4.6 Data Collection Service Timeout
4.7 Downstream Passthrough Error
5. Troubleshooting Quick Reference
Always returns code: 401
Check whether the API Key is correct, whether it has expired, and whether the Authorization header format is Bearer <api_key>.
Occasionally returns code: 429
Check whether the plan QPS limit has been exceeded. Increase retry intervals or upgrade the plan.
Returns code: 400 and contains Missing query
Check whether all required business parameters are provided.
Returns code: 400 and contains can't be used together
Check whether mutually exclusive parameters are provided together.
Returns code: 504 or a code: 400 data collection pipeline message
Temporary server-side issue. Retry later. If it persists, contact support and provide the original data message.
Returns Package has expired!
The plan has expired or the balance is insufficient. Renew the plan.
Returns Not supported for use in mainland China
Switch to an overseas network, or contact support to apply for whitelist access.
If you encounter an error message not listed in this document, provide the complete request parameters and response content to support so the issue can be identified quickly.
Last updated