Handling indexing API errors

Two families of error

When a call to an indexing API fails, the first question is whether sending it again could ever succeed. A wrong key, a malformed body or a job ID from another account will fail the same way every time; the fix is in the client or the account. A rate limit or a temporary server problem will clear by itself, and a delayed retry is correct. Mixing the two up produces the classic failure modes: a tight loop hammering a 401, or a script that gives up on a 429.

The tables below list what the IndexChex API returns, verbatim. IndexChex publishes this handbook; the endpoint reference is on its API documentation.

v1 responses

v1 errors carry a message field. Validation errors add an errors object keyed by field name.

Successful create calls return 202; status, report and balance calls return 200.

v2 responses

v2 keeps the SpeedyIndex envelope, so errors carry a numeric code alongside the HTTP status. The exception is authentication, which returns the same 401 body as v1 with no code.

The single-URL endpoint POST /v2/google/url returns a bare {"code": 2} with HTTP 500 on a temporary failure and {"code": 0} on success. Migration notes for v2 are in migrating a SpeedyIndex integration.

A Python handler

import time, requests

class PermanentError(Exception): pass
class RetryLater(Exception): pass

def call(method, url, headers, retries=5, **kw):
    for attempt in range(retries):
        r = requests.request(method, url, headers=headers, timeout=30, **kw)
        if r.status_code in (200, 202):
            return r.json()
        body = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
        msg = body.get("message", r.text[:200])
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", 30)))
            continue
        if r.status_code >= 500:
            if method == "POST":
                raise RetryLater(f"create may or may not have succeeded: {msg}")
            time.sleep(2 ** attempt * 5)
            continue
        if r.status_code == 422 and "not ready" in msg.lower():
            raise RetryLater(msg)
        raise PermanentError(f"{r.status_code}: {msg} {body.get('errors', '')}")
    raise RetryLater(f"gave up after {retries} attempts")

Three decisions are built in. Rate limits are waited out using the server's Retry-After header. Server errors on reads are retried with exponential back-off, but on create calls they are raised, because the job may already exist. And "report not ready" is surfaced as a retry-later signal rather than a failure, so the caller can go back to polling.

Avoiding errors in the first place

• Validate before sending. Trim, deduplicate and drop blank lines; keep name short; cap each job at 10,000 URLs, or 1,000 for instant. Rate limits and batching has a chunking helper.
• Check the balance first. GET /v1/balance returns {"balance": N}. Compare it with the URL count (times 60 for instant, plus 1 per URL for a scheduled check) before creating a job.
• Send Accept: application/json. Without it, some validation failures may not come back as JSON.
• Store job IDs immediately. Most 404s in practice come from IDs lost or mixed up between accounts.

Errors that are not errors

A finished index check can list URLs under failed_links. Those lookups could not complete; the API call itself succeeded. Likewise, a completed submission with URLs that later prove unindexed is not a failure of the request: IndexChex guarantees Googlebot crawling, and indexing remains Google's decision. How to read those results is covered in checking index status via an API and submitting URLs via an API.

Related

Error semantics are a fair test when comparing backlink indexer APIs and the wider category of backlink indexer software. The IndexChex entry lists the account-level API facts.