If the search request contains errors, the search returns a response that specifies where the error occurred. The default XML format response is described below. See the section on optional JSON output for an illustration of how this might differ if optional JSON output format was requested.
For example, given the following search query, which does not include the required
The results response (the elements are described below) should look like the following:
<wp:wp> <wp:result wp:type="error" wp:message="One or more input parameters are invalid" wp:code="Missing Input"/> <wp:errormessages> <wp:message>Missing Input: street</wp:message> </wp:errormessages> <wp:meta> <wp:linkexpiration>2008-04-01</wp:linkexpiration> <wp:recordrange wp:lastrecord="0" wp:firstrecord="0" wp:totalavailable="0"/> <wp:apiversion>1.0</wp:apiversion> <wp:searchlinks> <wp:link wp:linktext="Whitepages.com" wp:type="homepage">http://www.whitepages.com</wp:link> <wp:link wp:linktext="Link to this api call" wp:type="self"> URL_TO_THIS_API_CALL </wp:link> </wp:searchlinks> </wp:meta> </wp:wp>
URL_TO_THIS_API_CALL is the same URL as the original query
The data elements that may be found in an error response are described in the following table.
|result||The result status of the search request|
|type||The type of result||error means the request contained invalid or ambiguous data
success means the request returned 0 or more records
This attribute should be error in an error response.
|message||A textual description of the error|
|code||An error code||Found Data means that the search response contains at least one record
No Data Found means that the search response contains no records
Error means that an error occurred
Server Error means that a server error occurred
Invalid Input means that one or more of the input parameters was invalid
Mismatched Input means that two input parameters had conflicting data
Missing Input means that at least one required input parameter was missing
Refine Input means that the input data was ambiguous
|errormessages||Information pinpointing the cause of the error|
|message||The specific error message|
|linkexpiration||The date after which the links are no longer valid||Typically these are valid for several days.|
|lastrecord||The index of the last record in the list of records||This attribute should be 0 for an error response|
|firstrecord||The index of the first record in the list of records||This attribute should be 0 for an error response|
|totalavailable||The total number of returned records|
|apiversion||The version of the API||This is 1.0 for this release|
|link||A link to additional information related to the search|
|linktext||A textual description suitable for display|
|linktype||The type of link|
Error messages are intended to be self explanatory. Here are some of the common error messages.
Invalid or Inactive API key:API_KEYVAL - indicates that an invalid API_KEYVAL has been passed to WPAPI. Since an API_KEY takes about 10 minutes to activate, this can occur on first use of the WPAPI if less than 10 minutes has elapsed between registering for the API_KEY and first attempt at using it. Other common causes include a typo or transposition when entering the API_KEYVAL.
API key is required to use this API - indicates that the api_key parameter was entirely missing from the WPAPI call made. To correct this error add
where API_KEYVAL represents the API registration key you received when registering to the use the WPAPI.
Invalid Input Parameter:paramname - indicates that an input parameter was not recognized as a valid name of a parameter. The offending name will be identified as paramname in the message.
Missing Input:lastname - indicates that a required input parameter was not supplied. In this example the missing parameter was
Error Messages for Exceeding Limitations
If you exceed your 100 query per day limit or submit queries faster than 2 per second, you will receive an HTML error response 403 with a custom message indicating what limit has been exceeded. If you have exceeded a query per second limit, you may try your query again in the next second. If you have exceeded a query per day limit, you may try your query again on the next day.
Copyright © 2011 WhitePages.com. All rights reserved.
- WhitePages Pro API Test Account Documentation
- JSON Output
- Data Dictionary
- XML Schema Definition
- Frequently Asked Questions (FAQ)