Error Response

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 street parameter:

http://api.whitepages.com/reverse_address/1.0/?house=12345;city=seattle;state=wa;api_key=API_KEY

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>

where,
URL_TO_THIS_API_CALL is the same URL as the original query

Data Elements

The data elements that may be found in an error response are described in the following table.

Error Messages

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
   ;api_key=API_KEYVAL
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 lastname.

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.

Return to the main documentation page

Copyright © 2011 WhitePages.com. All rights reserved.