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/user_id/phone/email/address/vin 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 support@pipl.com.
403	Package key allowance reached	You have exceeded your package usage allowance	Please contact support@pipl.com.
403	Account suspended	Your API usage has been suspended.	Please contact support@pipl.com.
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	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 support@pipl.com.

Example Errors

Example Request: First name without last name

This would return an Error 400 response.

Shell

curl http://api.pipl.com/search/\?key=YOURKEY\&first_name=Clark

Python

from piplapis import search
search.SearchAPIRequest(first_name="Clark", api_key="YOURKEY").send()

Ruby

require 'pipl'
response = Pipl::client.search first_name: 'Clark', api_key: "YOURKEY"

Java

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

<?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();

C#

using Pipl.APIs.Search;

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

var request = new SearchAPIRequest(firstName: "Clark", requestConfiguration: searchConfiguration);
var response = request.SendAsync().Result;

HTTP

http://api.pipl.com/search/?first_name=Clark&key=YOURKEY

Example Request: Short or invalid phone number

This would return an Error 400 response.

Shell

curl http://api.pipl.com/search/\?key=YOURKEY\&phone=12345678

Python

from piplapis import search
search.SearchAPIRequest(phone="12345678", api_key="YOURKEY").send()

Ruby

require 'pipl'
response = Pipl::client.search phone: '12345678', api_key: "YOURKEY"

Java

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().phone("12345678").configuration(configuration).build();
SearchAPIResponse response = request.send()

PHP

<?php

require_once './piplapis/search.php';

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

$request = new PiplApi_SearchAPIRequest(array('phone' => '12345678'), $configuration);
$response = $request->send();

C#

using Pipl.APIs.Search;

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

var request = new SearchAPIRequest(phone: "12345678", requestConfiguration: searchConfiguration);
var response = request.SendAsync().Result;

HTTP

http://api.pipl.com/search/?phone=12345678&key=YOURKEY

Example Error Responses

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 - Account suspended

{
    "@http_status_code": 403, 
    "error": "Your API usage has been suspended. Please contact your account manager or support@pipl.com"
}

Example Response: Error 500 - Internal error

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