> For the complete documentation index, see [llms.txt](https://docs.talordata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talordata.com/serp-api/explanation-of-api-status-codes-and-error-codes.md).

# 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

| Item                 | Description                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 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:

| Scenario             | Response body example                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------- |
| 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 == 0` means success. Any other value means failure. The `data` field contains a human-readable error description.

***

### 2. Error Code Overview

| code  | Meaning                                                              | General category                               |
| ----- | -------------------------------------------------------------------- | ---------------------------------------------- |
| `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.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><code>data</code> message</td><td>Meaning</td><td>Suggested action</td></tr><tr><td><code>apikey is empty!</code></td><td>The request does not include the <code>Authorization</code> header.</td><td>Check whether the request header contains <code>Authorization: Bearer &#x3C;api_key></code>.</td></tr><tr><td><code>API key authentication failed：error-1</code></td><td>The <code>Authorization</code> header format is incorrect. It does not use the <code>Bearer &#x3C;token></code> format.</td><td>Change it to <code>Authorization: Bearer &#x3C;api_key></code>.</td></tr><tr><td><code>API key authentication failed：error-2</code></td><td>The API Key after <code>Bearer</code> is empty.</td><td>Enter a valid API Key after <code>Bearer</code>.</td></tr><tr><td><code>API key authentication failed：error-3</code></td><td>The authentication service is temporarily unavailable (cached as a failed state).</td><td>Retry later. If the issue persists, contact support.</td></tr><tr><td><code>API key authentication failed：error-4</code></td><td>The authentication service request failed.</td><td>Retry later. If the issue persists, contact support.</td></tr><tr><td><code>API key authentication failed：error-5</code></td><td>The authentication service response is abnormal.</td><td>Retry later. If the issue persists, contact support.</td></tr><tr><td><code>API key authentication failed：error-6</code></td><td>The API Key is invalid (does not exist or has been disabled).</td><td>Check in the user center whether the API Key is correct and whether it has been disabled.</td></tr><tr><td><code>Your API key has expired and is no longer valid.</code></td><td>The API Key has expired.</td><td>Renew your plan or replace it with a new API Key.</td></tr></tbody></table>

#### 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.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><code>data</code> message</td><td>Meaning</td><td>Suggested action</td></tr><tr><td><code>Parameter error</code></td><td>Failed to construct the data collection request, usually due to URL parsing failure.</td><td>Check whether the input parameters are valid. You may retry once.</td></tr><tr><td><code>The data collection API returned incorrect parameters!</code></td><td>The data collection service returned an unrecognized result.</td><td>Retry later. If the issue persists, contact support.</td></tr><tr><td><code>Internal parsing error</code></td><td>Failed to parse the inner data collection result.</td><td>Retry later. If the issue persists, contact support.</td></tr><tr><td><code>json value is not valid</code></td><td>The <code>json</code> parameter value is invalid. Only <code>1</code>, <code>2</code>, <code>3</code>, and <code>5</code> are supported.</td><td>Change it to a supported value.</td></tr><tr><td><code>JSON data retrieval failed</code></td><td>Failed to retrieve JSON data from the collection result.</td><td>Retry later.</td></tr><tr><td><code>HTML data retrieval failed</code></td><td>Failed to retrieve HTML data from the collection result.</td><td>Retry later.</td></tr><tr><td><code>HTML fetch failed: ...</code> / <code>JSON fetch failed: ...</code></td><td>When <code>json=2</code>, concurrent HTML and JSON retrieval failed. Multiple errors may be concatenated.</td><td>Retry later.</td></tr></tbody></table>

#### 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.

| Field  | Source                                                                         |
| ------ | ------------------------------------------------------------------------------ |
| `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

```
{
  "data": { "task_id": "xxxx", "result": { "...": "..." } },
  "code": 0
}
```

#### 4.2 Parameter Error

```
{
  "data": "Missing query `q` parameter",
  "code": 400
}
```

#### 4.3 Authentication Failed

```
{
  "data": "API key authentication failed：error-6",
  "code": 401
}
```

#### 4.4 API Key Expired

```
{
  "data": "Your API key has expired and is no longer valid.",
  "code": 401
}
```

#### 4.5 Rate Limited

```
{
  "data": "Too Many Requests",
  "code": 429
}
```

#### 4.6 Data Collection Service Timeout

```
{
  "data": "Data collection API request timeout!",
  "code": 504
}
```

#### 4.7 Downstream Passthrough Error

```
{
  "data": "Specific error message returned by the downstream service",
  "code": 500
}
```

***

### 5. Troubleshooting Quick Reference

<table data-search="false"><thead><tr><th>Symptom</th><th>Check first</th></tr></thead><tbody><tr><td>Always returns <code>code: 401</code></td><td>Check whether the API Key is correct, whether it has expired, and whether the <code>Authorization</code> header format is <code>Bearer &#x3C;api_key></code>.</td></tr><tr><td>Occasionally returns <code>code: 429</code></td><td>Check whether the plan QPS limit has been exceeded. Increase retry intervals or upgrade the plan.</td></tr><tr><td>Returns <code>code: 400</code> and contains <code>Missing query</code></td><td>Check whether all required business parameters are provided.</td></tr><tr><td>Returns <code>code: 400</code> and contains <code>can't be used together</code></td><td>Check whether mutually exclusive parameters are provided together.</td></tr><tr><td>Returns <code>code: 504</code> or a <code>code: 400</code> data collection pipeline message</td><td>Temporary server-side issue. Retry later. If it persists, contact support and provide the original <code>data</code> message.</td></tr><tr><td>Returns <code>Package has expired!</code></td><td>The plan has expired or the balance is insufficient. Renew the plan.</td></tr><tr><td>Returns <code>Not supported for use in mainland China</code></td><td>Switch to an overseas network, or contact support to apply for whitelist access.</td></tr></tbody></table>

***

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.