Introduction
The following errors apply to ALL Factual API requests. Each Factual API method may also have a set of errors specific to them. Those errors are documented within each method's documentation.
IMPORTANT: Unlike previous versions of the Factual API, requests that result in error responses no longer return HTTP 200 status codes. Instead, they return the appropriate HTTP error code appropriate to the error condition. In all cases, the response will still contain more specific error messages. It is highly recommended that you utilize a library that will enabled you to access the body of the HTTP response even if the response yielded a non-200 status.
Sample Response
Requests to the Factual API that result in errors will result in an HTTP error code in the response header for automated handling of the response. In addition, human readable error information will be provided in the form of JSON in the response similar to the following:
Error Responses
HTTP Error code | Factual Error Type | Message | Cause |
|---|---|---|---|
400 | InvalidArgument | Unrecognized parameter: parameter | Request contains a parameter that is unrecognized by the API method |
401 | Auth | You must provide an API Key for this request. Please contact Factual for a beta API key. | (Required) key parameter was not provided in the request. Note: If you are using curl to request data, KEY is a reserved word. You must escape it using backslash or you will receive this error. |
401 | Auth | The API key provided is invalid. To request a V3 Beta key, please visit http://www.factual.com/devtools/beta | (Required) key parameter was not provided in the request. |
401 | Auth | Your OAuth signature could not be verified. Please see http://developer.factual.com/display/docs/Core+API+-+Oauth | The OAuth signature does not match the request. |
403 | Auth | You have exceeded the throttle limit for this request. | Your key has attempted to make more requests than allotted to it either per minute or per day. For more information about throttle limits, go here. As an OAuth user, your key may have custom limits provisioned on a case-by-case basis – please contact factual directly for more information. |
403 | Auth | You do not have access to the requested resource. | Owner of the key specified in the request does not have access to the table requested |
403 | Auth | Unrecognized API method: method | Owner of the key specified in the request attempted a non-existent method |
403 | Auth | The method method is not allowed on this table. | Owner of the key specified in the request does not have access to the method requested on the target table |
403 | Auth | Illegal parameter: parameter | Request contains a parameter that is not allowed by the API method on the target table |
404 | Auth | Requested resource could not be found. | Owner of the key specified in the request attempted to access a non-existent table |
| 500 | Internal | Whoops! | You've encountered an error Factual has not predicted. Essentially, an uncaught exception. |
503 | Service | The resource requested is unavailable temporarily. | The request can't be fulfilled temporarily due to system maintenance |