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
| Condition | Action |
|---|---|
429 rate_limited | Wait for Retry-After. |
Retryable 503 | Follow Retry-After when present. |
401 or 403 | Check the key, scope, and Site access. |
| Empty successful rows | Check 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.