Skip to main content
The ScanURL API uses standard HTTP responses along with a structured JSON format to indicate errors. When a request fails, the API returns:
  • success: false
  • an error message describing the issue

​
Error Response Format

{
  "success": false,
  "message": "Error description"
}

​
Common Error Scenarios

​
Unauthorized Request

Occurs when the API key is missing or invalid. 
{
  "success": false,
  "message": "Unauthorized request"
}
How to handle:
  • verify that x-api-key header is included
  • ensure the API key is correct and active

​
Invalid Request

Occurs when the request body is incorrect or missing required fields. 
{
  "success": false,
  "message": "Invalid request"
}
How to handle:
  • ensure the request body contains a valid url field
  • validate input before sending the request

​
Scan Failure

Occurs when the system is unable to complete the scan. 
{
  "success": false,
  "message": "Scan failed"
}
How to handle:
  • retry the request after a short delay
check if the target URL is reachable

​
Timeout or Delayed Response

In some cases, complex pages may take longer to process. How to handle:
  • implement request timeout handling in your application
  • allow retries if needed

​
HTTP Status Codes

Status CodeMeaning
200Request processed (success or scan result returned)
400Bad request (invalid input)
401Unauthorized (invalid or missing API key)
500Internal server error

​
Best Practices for Handling Errors

  • always check the success field before using response data
  • handle authentication errors separately
  • retry failed or timed-out requests when appropriate
  • avoid assuming a failed request means the URL is safe

​
Summary

Error handling ensures your application can safely and reliably interact with the ScanURL API, even when requests fail or external conditions affect scanning.