---
title: "Hosted HTTP"
description: "Call typed v1 operations and handle API errors, rate limits, and retries."
canonical_url: "https://gscdump.com/gscdump-sdk/api/hosted-http"
last_updated: "2026-10-03T07:15:32.057Z"
---

# Hosted HTTP

Import `createGscdumpV1Client` from `@gscdump/sdk/v1`.
Each registered operation has a typed convenience method.
You can also pass its operation ID to `client.execute()`.

The client validates request and response payloads against the generated contracts.

## API specifications

Generate OpenAPI and AsyncAPI documents from the published contracts package:

::pre{tabindex="0"}
```bash
pnpm add @gscdump/contracts
```
::

::pre{tabindex="0"}
```ts
import { writeFile } from 'node:fs/promises'
import { createGscdumpV1Documents } from '@gscdump/contracts/v1'

for (const [name, document] of Object.entries(createGscdumpV1Documents())) {
  await writeFile(name, JSON.stringify(document, null, 2))
}
```
::

The function returns three OpenAPI documents: partner, analytics, and realtime HTTP.
It also returns the realtime AsyncAPI document.
Each document defines inputs, responses, scopes, and operation semantics for your installed package version.

## Errors

API failures use one JSON envelope:

::pre{tabindex="0"}
```json
{
  "error": {
    "code": "site_not_found",
    "message": "Site not found",
    "requestId": "req_01",
    "retryable": false,
    "details": {}
  }
}
```
::

Branch on `code` and `retryable`. Treat `message` as display text. Include
`requestId` when reporting a failure. The SDK exposes the same fields through
`GscdumpV1Error`:

::pre{tabindex="0"}
```ts
import {
  createGscdumpV1Client,
  isGscdumpV1Error,
} from '@gscdump/sdk/v1'

const gscdump = createGscdumpV1Client({
  credential: () => process.env.GSCDUMP_API_KEY!,
})

const result = await gscdump.getSiteIndexing({
  params: { siteId: 's_01' },
  query: {},
}).catch((error: unknown) => {
  if (isGscdumpV1Error(error)) {
    console.error(error.code, error.requestId, error.retryable)
    return null
  }
  throw error
})
```
::

Each OpenAPI operation lists its closed API error set in
`x-gscdump-errors`. The SDK also reports local credential, request,
transport, and response validation failures with the same tagged error class.

Successful responses use `{ "data": ..., "meta": ... }`. `meta` includes the
request ID, surface, and wire version. Every HTTP response also carries
`x-request-id`, `GSCdump-API-Version: 1.0`, `Cache-Control: private, no-store`,
and `Vary: Authorization`.

## Rate limits

The host applies rate limits per authenticated principal and operation.
Use the response headers to determine the remaining quota and reset time.

Quota-evaluated responses include `RateLimit-Policy` and `RateLimit`. On
`429 rate_limited`, wait for the `Retry-After` duration. Treat it as
authoritative. If the limiter is unavailable, the host fails closed with a
retryable `503 internal_error` and `Retry-After: 5`.

The SDK honors `Retry-After` when the operation descriptor allows a retry.

## Idempotency and retries

The OpenAPI `x-gscdump-semantics` object records whether an operation is
idempotent and whether the SDK may retry it. Check each operation before retrying it.

Five mutations are non-idempotent and use `retry: "never"`:

- `partner.sites.indexing.inspect.create`
- `partner.sites.sitemaps.action.create`
- `partner.teams.create`
- `partner.users.api_keys.create`
- `realtime.tickets.create`

The SDK does not automatically retry those five operations. After an ambiguous
network failure, read authoritative state before deciding whether to issue
another mutation. A realtime reconnect always requests a new ticket because
tickets are single-use.

For operations marked `retry: "idempotent"`, the SDK defaults to three total
attempts and caps configuration at five. It retries network failures and API
errors whose envelope says `retryable: true`. The backoff starts at 250 ms,
caps at two seconds, and waits longer when `Retry-After` requires it.

V1 currently has no public result-replay contract for `Idempotency-Key`. A
client-supplied key does not make a non-idempotent operation safe to retry.

## Sitemap

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