---
title: "Handle hosted API errors and retries"
description: "Read typed failures, respect Retry-After, and avoid duplicate mutations."
canonical_url: "https://gscdump.com/gscdump-sdk/guides/operate/errors-and-retry"
last_updated: "2026-10-03T07:15:32.064Z"
---

# 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

::pre{tabindex="0"}
```ts
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

::table{tabindex="0"}
| 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](/gscdump-sdk/api/hosted-http#rate-limits) 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](/gscdump-sdk/guides/read-data/hosted-indexing). 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](/gscdump-sdk/guides/operate/keys-and-scopes).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.