Why was my link refused?

Blinkhop refuses a link when the URL, the custom ending or the request breaks a rule, and the error code tells you which one. The website shows a short message, and the API returns a JSON error like this:

{"error": {"code": "invalid_url", "message": "...", "field": "url"}}

The same rules for URLs and custom endings apply on the website, the API and the MCP server.

Why the URL was refused

• missing_url: No URL was sent. Put the long link in the url field.
• invalid_url: The text isn’t a valid public web address. URLs with embedded credentials (user:pass@) and private or local addresses are refused too. Check for typos and spaces, remove any user:pass@ part, and use a public address.
• already_short: The URL is already a zou.sh link. Share that link as it is, or shorten the original long URL.
• url_too_long: The URL is longer than the maximum we accept. Remove tracking parameters you don’t need.
• unsafe_destination: The destination is flagged for phishing or malware. Don’t share it. If you think it’s a mistake, contact us with the URL.

Why the custom ending was refused

• invalid_alias: The ending breaks the rules. Use 3 to 40 letters, numbers, dashes or underscores, starting with a letter or a number.
• alias_taken (409): Another link already uses this ending (letter case is ignored), or the word is reserved. Pick a different ending.

How do I choose a custom ending? lists the rules and reserved words.

Why the request was refused

• rate_limited (429): Your IP address reached 20 new links per minute or 300 per day. Wait, then try again. Through the API, the Retry-After header says how long.
• not_found (404): The short link or the API endpoint doesn’t exist. Check the code and the path.
• invalid_json: The request body isn’t valid JSON. Check quotes, commas and brackets. In a shell, wrap the JSON in single quotes.
• too_large: The request body is too big. Send a smaller request, for example fewer URLs in a bulk request.

What are the API rate limits? explains the limits in detail.

Still stuck? Contact us with the error code and the URL you tried.