#5.1 : Result and Response: Status messages & codes

The response is in JSON format and contains the following fields:

STATUS

Contains the status of the API request and the result.

PARAMETER		FIELD DESCRIPTION
status		"message" = system message "code" = status code - see status code list below "type" = string, value can be: "No data yet": URL is not known yet by hyScore "Ok": request was successful, all seems well "Error": an error occurred, see status code "Incomplete": the analysis result is not complete yet, try again or come back later.  Special: with Error code: "13" an additional field "httpErrorCode" is provided. See status code list below.

EXAMPLES

Some examples of how a status message can look like.

### NEW URL ###

Everything works fine. The analysis is in progress. We've never seen this URL before. 

RESPONSE STRUCTURE

"status": {"type":"No data yet","message":"New URL, analysis in progress", "code": 0}

### SUCCESS MESSAGE ###

Everything works fine. Analysis successful, status (code: 1)

RESPONSE STRUCTURE

"status": {"type":"OK", "message":"All seems well.","code":1}

### INCOMPLETE MESSAGE ###

"Incomplete" status (code: 9) is returned if you request a URL which is currently in an analysis. We have received the URL (code: 0, New URL, analysis in progress), but the analysis for this specific URL has not been finished yet (code: 9)

"Incomplete" status (code:10) is shown if something went wrong with determining weighted keywords or a correct category, e.g. tagged, retry, notfound, nomatches, see "categorization" status (code: 10). This is a temporary status until an additional analysis takes place automatically and a result is available. It makes sense to queue these kinds of URLs Status and request it a couple of seconds or minutes later again (in a one-time analysis, depending on the content). In real-time cases, you get the full result usually with one of the next requests.

RESPONSE STRUCTURE

"status": {"type":"Incomplete","message":"Analysis in progress.","code":9}

"status": {"type":"Incomplete","message":"Analysis issues.","code":10} 

### ERROR MESSAGE ###

Something went wrong. "Houston! We've got a problem."

RESPONSE STRUCTURE

Without http-error

"status": {"type":"Error","message":"Empty body","code":15} 

With http-error

"status": {"type": "Error", "message": "Target URL returned non-200 HTTP Code", "code":13, "httpErrorCode": 418} 

---

LIST OF STATUS CODES

Some examples of how a status message can look like.

### NEW AND UNKNOWN URL ###

CODE: 0

New URL, analysis in progress. We haven't seen this URL before and need to analyze it first. request the URL again or come back later to gather the result.

 

### OK ###

CODE: 1

Ok. All seems well. Everything works fine. Analysis successful completed.

 

### INCOMPLETE ###

CODE: 9

Analysis in progress: Status code: 9 is returned if you request a URL which is currently in an analysis. We have received the URL (code: 0; New URL, analysis in progress), but the analysis for this specific URL has not been finished yet (code: 9). This new status was implemented to avoid multiple analysis requests for the same URL within a short time period. The URL is within hyScores' analysis pipeline, but there is no result or a partial result available yet. 

(Implemented: 13th August 2018)

CODE: 10

Incomplete: Something went wrong, e.g. categorization issue. We are not able to provide a full result yet. Come back later or try again. 

### ERROR ###

CODE: 11

Target URL not reachable: Crawler could not create a connection to the provided URL. Usually a time-out or connection error.

CODE: 12

URL blocked by robots.txt: The website disallows crawling. This can be fixed by whitelisting the hyScore.io user-agent and/or crawler IP-addresses. More information. 

CODE: 13

Target URL returned non 200 HTTP Code: Provides an additional field "httpErrorCode" with RFC standard codes, only if it's not explicitly covered by another error code (i.e 429 - too many requests), usually a 4xx/5xx error. See the example section above. 

CODE: 14

Unparseable body: Website body could not be decoded, usually the fault of an illegal charset.

CODE: 15

Empty body: Website was crawled successfully but has no or an empty <body>. Nothing to analyze. 

CODE: 16

Unknown host: Crawler could not resolve the domain. This usually means the domain does not exist or is offline. 

CODE: 17

Too many requests: Crawler was blocked by host because it sent to many requests (HTTP error code 429). This can be fixed by whitelisting the crawler. More information. 

CODE: 98 

URL Blocked by hyScore: URLs from this specific Domain are in general problematic and are blocked by default. Please contact the hyScore.io support if you have additional questions. 

Implemented: 13th August 2018

CODE: 99

Problematic URL: Technical difficulties while crawling this URL. This might be pure IP addresses with no content, ad server URLs, AWS S3 URLs or something similar.  

---

 

GENERAL ERROR

"message": "Forbidden" : No OR wrong API-Key. Authentification with the API failed.   

"message": "Limit exceeded" : The daily or monthly quota/limit of API requests for your API Key exceeds the configured volume. Please contact us or wait until the next month starts.