Understanding Response Codes From Tenon API
Tenon API uses HTTP Status codes to indicate whether your request was a success or failure. We also provide some additional information useful in determining the nature of the failure. The following example illustrates the relevant portion of our JSON response at which you'll locate this information:
- status: the HTTP status code.
- message: The associated message for the code, per RFC 2616.
- code: a token string showing what the response was.
- moreInfo: an URL to a more detailed explanation of the code.
Success Codes
'success'
The 'success' codes is easy to understand. This code means all went well with the request. All required parameters were set, the API key was valid, the supplied parameters were valid, the test document was reachable, and we were able to successfully perform our testing and return a response.
Example:
Failure Codes
Service Issues
The following failure codes represent that something went wrong on our end. Performance of our service is highly important to us. If you experience repeated performance issues please contact us so that we may investigate what is happening.
'internal_server_error'
This means an exception happened on our end. Our system is currently running at 99% success rate, meaning 99% of requests run without issue. If you get a 500 error, chances are, you can re-run your request without issue, so we recommend that in your final implementation, if you get a 500 error, retry once or twice. Re-running more than twice is a bad idea because, in our own use of the system we never see more than two 500s in a row unless something is wrong.
Important: In some cases, customers have discovered that Tenon's API will throw a 500 error if their site uses a restrictive CSP (content security policy) or Web Application Firewalls (WAF) such as Akamai or Cloudflare. You may need to ease up on the settings for your WAF or modify the content-security-policy header temporarily to allow Tenon's API to do its testing. Because Tenon does its testing by injecting JavaScript into the tested page, you may need to modify your CSP policy to list Tenon as a script-src. For SaaS or Private Cloud customers, you'll want to use a script-src value of https://*.tenon.io. For Enterprise On-Premises customers, you'll want to point to the domain of your Tenon instance.
Example
'request_timeout'
This means that the overall process took longer than we allow. The average successful response time is between 4 - 7 seconds for most requests - that's from the time you submit your request to the time we return a response. We actually wait much longer for the process to complete, so if you get this response, something went wrong. However, the issue may be on your side. Request timeouts tend to happen for one of three reasons:
- Something's wrong with your JavaScript: either your JavaScript has uncaught exceptions or your page never fires the onload event. In the latter case, we attempt to overcome this on our end but sometimes it just doesn't workout and we just kick it back.
- Your page includes third party content or features that never finish loading. Related to the above, sometimes timeouts are caused by third party stuff that never finishes loading
- Your page's performance is too slow.
- Your page's accessibility issues are so numerous that testing & processing takes so long that the process times out. This is actually a severe edge case, as we've seen pages with as many as 1800 errors that still responded, so this is far less likely than the other two cases, but still probable.
The issue in your case may be one of the above or a combination of the above. Regardless, we recommend investigating what the issue may be. This is especially true if you get multiple 522 responses. While a single 522 response here and there likely resides on our end, multiple 522 responses for multiple pages on the same site is likely to mean something to do with your code. In that case, you should investigate page performance, looking specifically for uncaught exceptions in your JavaScript.
Example
Request Issues
400 & 401 status responses are likely to be the most common failure responses you'll find and are due to issues with your request.
api_credentials_invalid
User supplied an invalid API key. To fix this issue, ensure that you're using the correct API key.
Example
monthly_limit_reached
User submitted more requests today than their plan's monthly limit allows. To fix this issue, upgrade your plan to one which allows more requests per month.
Example
expired_plan
User's subscription or trial has expired and must be renewed before continuing to use the system. To fix this issue, ensure that your plan and payment method is up to date.
Example
method_not_allowed
The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
Example
not_found
A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
Example
unsupported_media_type
A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
Example
blank_url_or_src
The parameter supplied for src was blank/ missing and the parameter supplied for url was also blank. To fix this issue, ensure that you've supplied a valid value in either the 'url' or 'src' parameters.
Example
bad_src
The parameter supplied for 'src' was not HTML. To fix this issue, ensure that the value you supply in the 'src' attribute consists only of HTML, CSS, and JavaScript.
Example
invalid_param
User supplied a parameter value that is outside of the expected range. The specific parameter and a related message will be returned in the API response under 'log'. To fix this issue, ensure all request parameters are valid.
Example
abuse_detected
User attempted to submit an abusive request to the system.
Example
required_param_missing
A required parameter was omitted from the request. The required parameters are 'key' and either 'url' or 'src'. To fix this issue, ensure that all required parameters have been set and are valid.
Example
doc_source_too_big
The size of the document submitted was too big. Although this is extremely rare, to fix this issue, ensure that the document source is smaller than 2Mb.
Example
improper_content_type
The content type detected from the supplied URL was not a web page. To fix this issue, ensure that the content of the URL supplied is an actual web page.
Example
url_request_failed
The URL supplied did not return a good HTTP response. The Test API looks for HTTP 200 or an HTTP 301 that redirects to an URL that returns HTTP 200. If your URL returns any 4xx or 5xx response code, you will see this issue.