Errors and troubleshooting
Resolve AIHackr API authentication, URL, robots, rate-limit and crawl errors. Use error codes to decide when to correct a request or retry.
On this page
Read the error response
Check the HTTP status before treating a response as content. Errors use success: false with a structured code and message. Do not retry every error indiscriminately.
{
"success": false,
"error": {
"code": "AUTH_REQUIRED",
"message": "Sign in to your AIHackr account or provide a valid API key."
}
}Common error codes
| Code / status | Likely cause | Next step |
|---|---|---|
| AUTH_REQUIRED / 401 | Missing, expired or revoked authentication. | Sign in again or replace the key. Keep the Bearer prefix. |
| ORIGIN_RESTRICTED / 403 | A browser request comes from another origin. | Call from your server or use the AIHackr playground. |
| INVALID_INPUT / 400 | Malformed URL, JSON or request fields. | Compare the body to the endpoint reference. |
| UNSUPPORTED_OPTION / 400 | An option is outside this API subset. | Remove it; do not assume SDK compatibility. |
| TARGET_RESTRICTED / 403 | Non-public target, credentials or unsupported port. | Use a public HTTP(S) URL. |
| ROBOTS_DISALLOWED / 403 | The target disallows crawling. | Choose a permitted source. |
| TARGET_ERROR / 422 | The target page returned an error. | Check that page directly and inspect its status. |
| TRIAL_LIMIT / 429 | The account’s lifetime trial is exhausted. | Inspect account usage; retrying will not restore pages. |
| DAILY_LIMIT / 429 | The shared daily service allowance is exhausted. | Wait for the next service day. |
| RATE_LIMITED / 429 | Concurrency, request or provider rate exceeded. | Respect Retry-After and back off. |
| ENGINE_UNAVAILABLE / 503 | A browser/provider operation could not complete. | Check the target and readiness; retry sparingly. |
| NOT_FOUND / 404 | Unknown or unavailable job/route. | Check the ID, owner account and retention window. |
The URL is present but the form rejects it
The playground accepts example.com and complete URLs. It adds HTTPS to a bare domain. Direct API requests require a complete URL such as https://example.com/. Avoid usernames, passwords and unsupported schemes.
Empty or incomplete content
Check for robots restrictions, target errors, JavaScript dependencies and truncation. A Map response can be empty when the submitted page has no matching same-origin links. A crawl is not complete until the workspace status is terminal; follow every next URL for retained records.
Report a reproducible issue
Open an issue in the source repository with the endpoint, sanitized request, timestamp, HTTP status and error code. Include a public example URL only when appropriate. Never post a key, email sign-in code, session cookie or private crawl output.