Entry: errors
Check domain score calls that fail: 401, 402 and empty rows
Entry: errors. Two HTTP codes carry meaning, one flag tells you whether a call completed, and one data property explains most surprises.
Symptom, cause, fix
| Symptom | Likely cause | Fix |
|---|---|---|
| HTTP 401 | Key missing, mistyped or revoked | Send key=sk_... or the Bearer header; copy the key again from the account page |
| HTTP 402 | Credit has run out | Top up in USDT (TRC-20); free actions still work |
| ok is false | The call did not complete | Read the HTTP status first, then the response body |
| Domain looks unscored | Few or no links in the index | Look at referring domains; DR of 0 means none were found |
| Recent link missing | Index refreshes roughly monthly | Wait for the next refresh; do not retry in a loop |
| Pages stop after 50,000 rows | Pagination cap | Narrow with a query or sort, then page again |
| Bulk call rejected | More than 2,000 domains | Split the list into chunks |
Payments are in USDT on the TRC-20 network. Sign-in is Google only. Bulk lists are capped at 2,000 domains, listing calls at 1,000 rows, and deep paging at 50,000 rows.
Order of diagnosis
Start with the status code. A 401 is about identity and a 402 is about money. They are fixed in different places.
Then read ok. Every response carries it. On authenticated calls, _credits shows the cost and the remaining balance, so a drained balance is visible before the 402 arrives.
Only after that should you suspect the data. A young site often shows a low DR. The cause is rarely a bug, and more likely the monthly snapshot predates its links. Compare the figure with the formula entry.
Minimal retry policy
- Never retry a 401 or 402 automatically
- Retry network failures with growing delays
- Stop when _credits shows a balance near zero
- Cache successful answers for the month
- Log the action and domain with each failure
Edge questions
Are credits deducted for a failed call?
We do not state a billing rule for failed calls in this reference. Watch _credits on the next authenticated response and compare the remaining balance with your expectation.
Why does a free action work after a 402?
Because domain, overview, stats and suggest need no key and no credit. Only paid actions are blocked once the balance is empty.
Where do field names come from?
See the API field entry for the general shape and call a live endpoint for action-specific rows.
Reproducing a failure for a bug report
Reduce to one call
Strip the loop and keep a single curl command that fails.
Record the response
Note the HTTP status, the value of ok and the _credits field if present.
Try a free action on the same domain
If overview works and the paid action does not, the fault is key or balance, not the domain.
Send the details
Write to us through the account page with the time, the action and the first and last characters of the key.
Where each fix lives
| Fix | Place |
|---|---|
| New or copied key | Account page |
| Top-up in USDT (TRC-20) | Account page |
| Chunking and retry | Your own client code |
| Waiting for a refresh | Nothing to do; the index updates roughly monthly |
Why not auto-retry
Looping on a 402 burns time and gains nothing. Looping on a 401 can trip abuse detection at any provider, ours or Google's.
Reserve retries for network errors, and give each retry a longer pause than the last. Three attempts is a sensible ceiling for a nightly job.
Our crawler and our link index refresh roughly once a month. A site launched in the last four weeks may show DR 0, and that is a correct reading of the snapshot.