Errors

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"
}