Skip to main content

​
Error response format

All error responses are JSON objects. The error field is always present. The detail field is included only for 500 responses. 
{
  "error": "<message>",
  "detail": "<additional info>"
}

​
HTTP status codes

StatusMeaningWhen it occurs
400 Bad RequestInvalid requestThe url field is missing from the request body or is not a string
429 Too Many RequestsRate limit exceededThe client IP has sent more than 100 requests in the current 15-minute window
500 Internal Server ErrorServer errorAn unexpected error occurred during URL analysis

​
400 Bad Request

Returned when the url field is absent or not a string. 
{
  "error": "Missing 'url' in body"
}

​
429 Too Many Requests

Returned when the rate limit is exceeded. The response includes the configured limit and the current request count for the client IP. 
{
  "error": "Too many requests from this IP, please try again later.",
  "limit": 100,
  "current": 101
}
The current field tells you how many requests this IP has made in the current 15-minute window. Use it to understand how far over the limit you are before backing off.

​
500 Internal Server Error

Returned when an unexpected error occurs while analyzing the URL. 
{
  "error": "Server error",
  "detail": "Error: connect ECONNREFUSED 127.0.0.1:443"
}
The detail field contains the stringified error (String(err)) for debugging purposes. Treat it as opaque in production — its format may change without notice and it may expose internal implementation details.
If Redis is unavailable, the rate limiter fails open: requests proceed normally rather than being blocked. Scan result caching is also skipped when Redis is unreachable. The service degrades gracefully — analysis continues using live checker calls.

Build docs developers (and LLMs) love

Get started for freeTalk to us