Sign In Register

Status and Error Codes

SerpApi uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a 200 code indicates success. Codes in the 4xx range usually indicate an error that failed given the information provided (e.g., a required parameter was omitted, ran out of searches, etc.). Codes in the 5xx range usually indicate an error with SerpApi's servers.

Please refer to the Search API Status and Errors section for guidance on how to handle errors in the Search API.

HTTP Status Codes
200 OK Everything worked as expected.
400 Bad Request We were unable to process the request. The request may be missing a required parameter.
401 Unauthorized No valid API key provided.
403 Forbidden The account associated with this API key doesn't have permission to perform the request. This usually happens if the account has been deleted.
404 Not Found The requested resource doesn't exist.
410 Gone The search expired and has been deleted from the archive.
429 Too Many Requests The number of requests sent using this API key exceeds the hourly throughput limit OR your account has run out of searches.
500, 503 Server Error Something went wrong on SerpApi's end. Please contact support@serpapi.com for assistance.

JSON structure overview 

{
  "error": "String - A human-readable message about the error."
}

Examples

Error for invalid API key

HTTP Status: 401 (Unauthorized)


JSON Example

{
  "error": "Invalid API key. Your API key should be here: https://serpapi.com/manage-api-key"
}

Error for no searches remaining

HTTP Status: 429 (Too Many Requests)


JSON Example

{
  "error": "Your account has run out of searches."
}

Error for missing parameter in Google Search API

HTTP Status: 400 (Bad Request)


JSON Example

{
  "error": "Missing query `q` parameter."
}

Search API Status and Errors

All of our Search APIs use the same error response structure. This includes all of our APIs except for the Extra APIs (Location API, Account API, Search Archive API etc.).

A search status is accessible through the search_metadata.status key. A search status begins as Processing, then resolves to either Success or Error. If a search has failed or contains empty results, the top level error key will contain an error message.

Note that if a search returns empty results due to no results returned by the search engine, it is still considered succesful from SerpApi's perspective and will have a status value of Success.

Search Status Description
Success Search request is successfully processed (It might include empty results).
Processing Search request is processing.
Queued Search request is queued for process.
Error Search process encountered an error before it could be completed (e.g. Proxy timeout, internal errors, etc).

JSON structure overview 

{
  "search_information": {
    "organic_results_state": "String - The result state for organic results (e.g. Fully Empty, Results for exact spelling). The key may not always be present if the search returns results. The key name varies by engine to reflect result type, i.e  'local_results_state', or 'finance_results_state', but always ending in '_state'",
  },
  "error": "String - A human-readable message about the error."
}

Examples

Status: Error

HTTP Status: 503 (Service Unavailable)


JSON Example

{
  "search_metadata": {
    "id": "64c32cfeb68f8bc186aaa013",
    "status": "Error",
    "json_endpoint": "https://serpapi.com/searches/d46c933a4a843289/64c32cfeb68f8bc186aaa013.json",
    ...
  },
  ...
  "error": "We couldn't get valid results for this search. Please try again later.",
}

Status: Success with empty organic results in Google Search API

HTTP Status: 200 (OK)


JSON Example

{
  "search_metadata": {
    "id": "6540ac26b68f8b2910019dd5",
    "status": "Success",
    "json_endpoint": "https://serpapi.com/searches/d1add70d119063c8/6540ac26b68f8b2910019dd5.json",
    ...
  },
  ...
  "search_information": {
    "organic_results_state": "Fully empty"
  },
  "error": "Google hasn't returned any results for this query."
}

Status: Success with spelling fixes in Google Search API

HTTP Status: 200 (OK).

error key is not present in this case because valid results are returned.


JSON Example

{
  "search_metadata": {
    "id": "6540ac26b68d3b2910019dd5",
    "status": "Success",
    "json_endpoint": "https://serpapi.com/searches/d3add74d149063c9/6540ac26b68d3b2910019dd5.json",
    ...
  },
  ...
  "search_information": {
    "query_displayed": "Coffe",
    "organic_results_state": "Some results for exact spelling but showing fixed spelling",
    "spelling_fix": "Coffee"
  },
  ...
}

Status: Success with empty local results in Google Maps API

HTTP Status: 200 (OK)


JSON Example

{
  "search_metadata": {
    "id": "6540af0b66440aef3efcbdd0",
    "status": "Success",
    "json_endpoint": "https://serpapi.com/searches/268f774b7d0b7072/6540af0b66440aef3efcbdd0.json",
    ...
  },
  ...
  "search_information": {
    "local_results_state": "Fully empty"
  },
  "error": "Google hasn't returned any results for this query."
}