Error codes and responses

When an error occurs, one of the HTTP status codes listed below will be returned. Depending on the error, more detail can be found in the returned JSON object which will have an error field and possibly an identifier field that should be provided if contacting Piano support. In some cases a details field might also be present containing additional details about the cause of the error.

For requests using response wrapping, the HTTP status code will be provided in the httpStatus field and the error object will be provided in the response field.

HTTP status codes

The following table provides an overview of the HTTP status codes you might encounter, and their semantics:

Code	Text	Description
200	OK	Request successful, no error.
400	Bad Request	Your request was invalid and not performed. One possible reason might be that the request refers to a resource that does not exist. See the error message for details, and below for some common examples.
401	Unauthorized	Missing or invalid authentication credentials provided.
403	Forbidden	Permission to perform the specific method, using the specific parameters or accessing the specific resource was denied. This will also be returned if you try to access the API over HTTP and not HTTPS. This might also be returned if the request refers to a resource that does not exist, to prevent users from using the APIs to determine which IDs refer to existing resources.
404	Not Found	The path used does not map to any API. 404 is not used for missing resources (i.e., cases where the API path is correct, but references a resource that does not exist); in these cases, 400 or 403 is used.
405	Method Not Allowed	Only GET and POST HTTP methods are supported.
413	Payload Too Large	The request object submitted to the API exceeded a limit set in place to ensure the availability of service. For batch requests, consider sending smaller batches. If this response is returned, processing of the request was not attempted, so retrying with a smaller batch is safe. The limit for the particular API call will be described in the response error field. Note that different API endpoints may operate with different limits, such that API endpoints designed for ingesting larger data volumes may accept larger requests than API endpoints that accept query operations.
429	Too Many Requests	The user has performed too many requests and has been rate limited. Clients are generally rate limited to ensure that a stable service can be provided for all customers. Details about the rate limiting will change over time, please contact your sales representative for pricing information before using the Insight API on a production site or service.
500	Internal Server Error	An unexpected internal error occurred. This error does not contain any details about why the failure occurred. Please notify Piano support using the provided reference.
500	Request expired	The provided date from the header is more than 5 minutes from now. This is a common issue with incorrect time, date or time zone settings on the customers machine. This could be caused by your computer clock being off, relative to Piano Insight as explain in the API Tutorial
503	Service Unavailable	No server was available to handle the request. Try again later or notify Piano support.
504	Gateway Timeout	The server was unable to handle the request before the timeout limit occurred. If you are attempting to perform multiple queries in a single request, split it into several requests.

Examples

$ curl -D - http://api.cxense.com/public/date

HTTP/1.0 403 Forbidden
Cache-Control: no-cache
Connection: close
Content-Type: application/json
Content-Length: 54


{"error":"Request forbidden by administrative rules."}

curl -D - https://api.cxense.com/profile/content/fetch


HTTP/1.1 401 Unauthorized
Server: nginx
Date: Mon, 31 Mar 2014 14:19:13 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 35
Connection: keep-alive
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
X-Content-Type-Options: nosniff

{"error":"Authentication required"}

$ cx.py /profile/content/fetch '{"url":"http://www.example.com"}'

{
  "error": "Invalid signature"
}

(The following errors, will happen slightly different with the now recommended cx.py, because it will run an early integrity check on the JSON request data and thus will prevent the request to Cxense)

$ python cxcurl.py -D - https://api.cxense.com/profile/content/fetch -d 'invalid'
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 47
 
{"error":"Invalid request: Invalid JSON input"}

$ python cxcurl.py -D - 'https://api.cxense.com/profile/content/fetch?callback=mycb&json=invalid'
HTTP/1.1 200 OK
Content-Type: text/javascript;charset=UTF-8
Content-Length: 80
 
mycb({"httpStatus":400,"response":{"error":"Invalid request: Invalid JSON input"}})

$ python cxcurl.py -D - https://api.cxense.com/profile/content/fetch -d '{"foo":"bar"}'
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 75
 
{"error":"Invalid request: Request object does not match method signature"}

Last updated: June 25, 2026