Errors
The API and the MCP server report errors with the same codes. The code is for your program, the message is for people.
{
"error": {
"code": "blocked_host",
"message": "Internal or private addresses are not scanned."
}
}The message comes in English with lang=en and in German otherwise, see Language. Its wording may change; the code stays the same. The table lists the HTTP status and the English message for each code.
When a check fails, the MCP server responds with a tool result in which isError is true. The text starts with the code, followed by the message, in English unless the call passes lang: "de", for example timeout: The site did not respond in time. The homepage endpoint GET /api/scan sends code and message as two plain fields, that is { "error": "timeout", "message": "…" }. More in the API reference.
| Code | Status | Message | Retry |
|---|---|---|---|
no_url | 400 | Please provide a URL. | No |
bad_url | 400 | This is not a valid address. | No |
bad_scheme | 400 | Only http:// and https:// are supported. | No |
blocked_host | 400 | Internal or private addresses are not scanned. | No |
dns_failed | 400 | The address could not be resolved. | Only once the DNS record exists |
unauthorized | 401 | API key missing or invalid. | No |
rate_limited | 429 | Too many requests. Please wait a moment. | Yes, after X-RateLimit-Reset |
server_error | 500 | Unexpected error. | Yes, once |
fetch_failed | 502 | The site could not be reached. | Yes, after a short pause |
tls_invalid | 502 | The site's HTTPS certificate is invalid. Browsers show a warning. | Only once the certificate is valid |
too_many_redirects | 502 | Too many redirects. | No |
not_configured | 503 | This feature is not set up yet. | No |
timeout | 504 | The site did not respond in time. | Yes, after a short pause |
Errors with status 400 are caused by the input. Retrying with the same address usually gives the same result. Errors from 502 upward are usually caused by the checked site or the network, and a second attempt after a few seconds often helps. With tls_invalid, the problem lies with the checked site, and browsers show a warning there as well. How to fix it is explained in the help article HTTPS and certificates.