Check my backlink returned nothing: an error table
Your tool is only as calm as its error handling. Below, the failures that actually happen, the exact cause, and whether a retry makes sense.
The rule that covers most cases
Retry network faults. Never retry 401 or 402. The first kind fixes itself in seconds; the second needs a human, and hammering it only fills your logs.
Every JSON response carries an ok field, and authenticated ones add _credits with the call cost and the remaining balance. Check ok on the body even when the HTTP status looks fine.
The retry timings below are our engineering advice, not documented limits. The API documentation we hold does not publish a rate limit, so build your own ceiling and keep it modest.
Symptom, cause, response
| Symptom | Cause | Retry? | What to do |
|---|---|---|---|
| HTTP 401 | Key missing, mistyped or revoked | No | Check the header or key= value, then the account page |
| HTTP 402 | Credit has run out | No | Top up in USDT (TRC-20) from the account page; same key resumes |
ok is not true on HTTP 200 | Bad parameter, such as a URL where a domain belongs | No | Validate input; send example.com, not https://example.com/page |
| Timeout or connection reset | Network or upstream blip | Yes, 3 to 4 times | Back off 1, 2, 4, 8 seconds with jitter |
| Empty result for a new site | Not in the index yet; refresh is monthly | No | Show "not indexed yet" with the index date |
| Number differs from another tool | Different index and a different DR formula | No | Compare trends within one tool, see DR reference |
| Rows stop at 50,000 | Pagination ceiling | No | See paging notes |
| Balance falls faster than planned | Paid action in a loop, or a 3-credit call on a hot path | n/a | Log _credits, allow-list actions |
Before blaming your code, paste the failing URL into cURL with the same key. If it works there, the bug is in your client. If it fails there too, the answer is in the table. This check has settled more tickets than any log search.
A debugging run, in order
- 1
Reproduce with curl
Take the failing URL out of your app and run it by hand with the same key. If curl works, your code is the problem.
- 2
Try a free action
overviewon the same domain needs no key. If it answers, the index is fine and the issue sits in auth or credit. - 3
Read the balance
A 402 is unambiguous, but a failing paid call after a free success usually points at credit or a typo in the key.
- 4
Check the input
Lowercase, no scheme, no path, no trailing dot. Most
okfailures end here.
Never print a raw upstream error in the interface. Map 401 and 402 to a generic "service unavailable" and send the detail to your own log and an alert. Visitors cannot fix your balance, and the message makes your tool look broken.
Related questions
- Can my users type any URL into the box?
- Let them, then normalise it yourself. Strip the scheme, the path, query string and
www.if you choose to, lowercase the host, and only then call the API. The upstream expects a bare domain, so unclean input is the commonest cause of a failed call. - Should I cache failures?
- Cache an empty "not indexed" result for a few hours, because the index only changes monthly. Never cache a 401 or 402 for long. Those clear the moment the key or balance is fixed, and a cached error would hide the fix.
- Do free actions count against anything?
- They cost no credits. The four free ones are
domain,overview,statsandsuggest. Still cache them, since being polite costs nothing and keeps your own latency low.