In some circumstances, the search query cannot be executed and the API will return an error.

Error Codes

Error codes you can expect to see:

Status Code

Description

400

Bad Request: either we could not decode your search request or it did not contain enough data for a search.

403

Calls Exceeded: you have either been rate-limited or you’ve reached your key quota, organization spend limit, or your account has been suspended.

500

Any other internal error.

Resolving Errors

The table below displays error messages for each error type. The column Error contains the exact error string returned from the Pipl API.

Status Code

Error Type

Error

Resolution

400

Bad request

The query does not contain any valid name/username/phone/email to search by

Check the warnings returned, and make sure the search request meets the minimum requirement.

403

Spend limit reached

You have reached your monthly spend limit.

Please contact your account manager.

403

Package key allowance reached

You have exceeded your package usage allowance

Please contact your account manager.

403

Account suspended

Your API usage has been suspended. Please contact your account manager or [email protected]

Please contact your account manager or [email protected]

403

Rate limited: Per second limit reached (without live feeds)

Per second limit for total calls reached.

You are making too many calls per second. Implement a throttling mechanism. Use the HTTP headers and adhere to the rate limits.

403

Rate limited: Per second limit reached (with live feeds)

Per second limit for live calls reached.

You are making too many calls per second. Implement a throttling mechanism. Use the HTTP headers and adhere to the rate limits.

403

Daily API key quota reached

Daily quota reached.

Change your key quota limit as required, or wait until the quota resets the following month.

403

Weekly API key quota reached

Weekly quota reached.

Change your key quota limit as required, or wait until the quota resets the following month.

403

Monthly API key quota reached

Monthly quota reached.

Change your key quota limit if required, or wait until the quota resets the following month.

403

Demo quota reached

You have exceeded your demo usage allowance.

Enter a payment method and upgrade to production ready keys.

403

Rate limited: Per second limit reached on demo key

Per second limit for demo calls reached.

Enter a payment method and upgrade to production ready keys.

403

SSL required

SSL is required to perform this operation. Please use https.

Change your protocol to use HTTPS. If you are using one of Pipl's Code Libraries please upgrade and/or set the flag to use https in configuration.

500

Internal error

Internal Server Error

Please contact Pipl Customer Support

Example Errors

Example Request: First name without last name

curl http://api.pipl.com/search/\?key=YOURKEY\&first_name=Clark
from piplapis import search
search.SearchAPIRequest(first_name="Clark", api_key="YOURKEY").send()
require 'pipl'
response = Pipl::client.search first_name: 'Clark', api_key: "YOURKEY"
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.search.SearchConfiguration;

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'

SearchAPIRequest request = new SearchAPIRequest.Builder().firstName("Clark").configuration(configuration).build();
SearchAPIResponse response = request.send()
<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';

$request = new PiplApi_SearchAPIRequest(array('first_name' => 'Clark'), $configuration);
$response = $request->send();
using Pipl.APIs.Search;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");

var request = new SearchAPIRequest(firstName: "Clark", requestConfiguration: searchConfiguration);
var response = request.SendAsync().Result;
http://api.pipl.com/search/?first_name=Clark&key=YOURKEY

Example Response: Error 400 - Bad Request

{
    "@http_status_code": 400, 
    "warnings": [
        "Parameter `first_name` ignored"
    ], 
    "error": "The query does not contain any valid name/username/phone/email to search by"
}

Example Response: Error 403 - Spend limit reached

{
    "@http_status_code": 403, 
    "error": "You have reached your monthly spend limit."
}

Example Response: Error 403 - Demo key quota reached

{
    "@http_status_code": 403, 
    "error": "You have exceeded your demo usage allowance."
}

Example Response: Error 403 - Account suspended

{
    "@http_status_code": 403, 
    "error": "Your API usage has been suspended. Please contact your account manager or [email protected]"
}

Example Response: Error 500 - Internal error

{
    "@http_status_code": 500, 
    "warnings": [], 
    "error": "Internal Server Error"
}