Index of every page on this site: llms.txt
Skip to content

Handle hosted API errors and retries

Catch a typed error at your server boundary. The SDK validates requests and responses against the v1 contract.

Catch a typed error

import { isGscdumpV1Error } from '@gscdump/sdk/v1'

try {
  const result = await client.queryAnalyticsRows({
    params: { siteId },
    body: { dimensions: ['query'], rowLimit: 100 },
  })
  console.log(result.data.rows)
}
catch (error) {
  if (!isGscdumpV1Error(error))
    throw error

  console.error({
    code: error.code,
    requestId: error.requestId,
    retryable: error.retryable,
  })
}

The error also carries a message and details. Log the request ID and code. Keep credentials and request headers out of logs.

Retry a safe request

ConditionAction
429 rate_limitedWait for Retry-After.
Retryable 503Follow Retry-After when present.
401 or 403Check the key, scope, and Site access.
Empty successful rowsCheck filters and coverage, do not retry blindly.

The SDK retries operations marked idempotent by default, up to three total attempts. It caps configuration at five. It honors Retry-After when a retry is allowed. Check the hosted HTTP reference for the current rule.

Avoid duplicate mutations

The SDK does not automatically retry non-idempotent operations such as new URL inspections, partner user key creation, and realtime ticket creation. A timeout after sending one leaves its outcome uncertain. A client-supplied Idempotency-Key has no public result-replay contract.

Recover an uncertain result

Read authoritative state before resending a mutation. For an inspection, check saved Indexing Evidence. A realtime reconnect always requests a new single-use ticket.

Report a failure

Record the operation, Site ID, error code, and request ID. Do not record the API key. For access failures, follow Keys and scopes.