Build a production-grade Guidewire Cloud API client that survives the request-side failures — 409 checksum conflicts on PATCH/PUT, 429 quota throttling, offsetToken pagination drift, retry-unsafe POSTs, and unstructured error responses. Use when designing an HTTP client wrapper around PolicyCenter, ClaimCenter, or BillingCenter REST endpoints. Trigger with "guidewire client", "guidewire sdk", "checksum 409", "guidewire pagination", "guidewire rate limit", "Retry-After".
Instrucciones de origen · Vista previa de solo lectura
name
guidewire-sdk-patterns
description
Build a production-grade Guidewire Cloud API client that survives the request-side failures — 409 checksum conflicts on PATCH/PUT, 429 quota throttling, offsetToken pagination drift, retry-unsafe POSTs, and unstructured error responses. Use when designing an HTTP client wrapper around PolicyCenter, ClaimCenter, or BillingCenter REST endpoints. Trigger with "guidewire client", "guidewire sdk", "checksum 409", "guidewire pagination", "guidewire rate limit", "Retry-After".
Build the Cloud API request layer that runs in production. This skill assumes the auth layer from guidewire-install-auth is in place — bearer tokens come from the cached token provider, not a static API_KEY. What this layer adds: safe mutations under optimistic locking, retry-aware writes, quota-friendly request pacing, complete pagination, and a typed error surface that business logic can pattern-match.
Five production failures this skill prevents:
409 Conflict storms — client GETs a record, lets the user (or workflow) edit it, then PATCHes back without the latest checksum; the next concurrent edit causes both PATCHes to lose.
429 cascades — every retry on 429 happens at the same backoff, all clients hammer the endpoint together, the tenant rate quota stays pinned.
Silent data loss in pagination — client treats pageSize=100 as "all results"; misses page 2 onward; reports inflated coverage to downstream.
Duplicate writes on retry — POST to create-claim times out at the load balancer, client retries, two claims land with the same FNOL.
Generic error handling — every non-2xx response collapses into "request failed", losing the userMessage, errors[].type, and attributes structure the API actually returns.
Prerequisites
A working auth layer per guidewire-install-auth — getToken() returning a cached, scope-validated bearer
Cloud API endpoints reachable on [TENANT].guidewire.net (PC/CC/BC base URLs in env)
Node 20+ or equivalent runtime supporting fetch, AbortController, and crypto.randomUUID
Familiarity with the Cloud API response envelope (data[], attributes, checksum, links) — see guidewire-install-auth/references/API_REFERENCE.md
Instructions
Implement the patterns below as composable layers on top of fetch. Each pattern targets one of the five production failures listed in Overview; do not skip any layer in production code.
1. Checksum round-trip for safe mutations
Every Cloud API resource carries a checksum. PATCH and PUT must echo the latest checksum in the request body, or the API returns to protect concurrent writers. Wrap mutations in a fetch-then-mutate helper that does the round-trip automatically.
When 409 still occurs (rare race), the caller should retry the helper itself, not the inner PATCH — the inner PATCH would just hit 409 again with the same stale checksum.
2. Retry-After-aware rate limiting
On 429 Too Many Requests, Cloud API returns a Retry-After header that is either an integer (seconds) or an HTTP date. Honour both forms; never use a fixed backoff. Combine with exponential-with-jitter for transient 5xx so concurrent clients do not synchronize their retries.
Cloud API does not page by number. The response carries links.next.href until the data is exhausted; absence of links.next is the terminator. Iterate as a generator so callers do not buffer the whole dataset.
exportasyncfunction* paginate<T>(path: string): AsyncGenerator<T> {
letnext: string | null = path;
while (next) {
const token = awaitgetToken();
const res = awaitfetch(`${BASE}${next}`, { headers: { Authorization: `Bearer ${token}` } });
if (!res.ok) throwawaitmapError(res, "GET", next);
const body = await res.json();
for (const item of body.data) yield item.attributesas T;
next = body.links?.next?.href ?? null;
}
}
4. Idempotency-Key for retry-safe writes
POST is not naturally idempotent. A timeout at the load balancer can cause the client to retry a request the API already processed — duplicate claim, duplicate payment, duplicate activity. Cloud API accepts an Idempotency-Key header; supplied keys deduplicate within a 24-hour window. Generate a v4 UUID per logical operation (not per HTTP attempt).
Cloud API error bodies are structured: { userMessage, errors: [{ message, type, attributes }] }. Lift the structure into a typed exception so business logic can pattern-match (if (e instanceof GwBusinessRuleError) rather than if (msg.includes("policy"))).
The helper performs GET, applies the mutation, PATCHes back with the latest checksum. If two services update the same policy simultaneously, one wins, the other gets 409 and can retry the helper for a clean re-merge.
Example 2 — Bulk import with quota-friendly pacing
constclaims: NewClaim[] = awaitloadFnolBatch();
for (const claim of claims) {
awaitretryable(() =>createClaim(claim)); // honours Retry-After on 429, jitter on 5xx
}
A 10,000-record batch import that respects the tenant quota without manual rate calculations. The single-flight token cache from guidewire-install-auth keeps Hub calls bounded as well.
Example 3 — Pagination without surprises
let total = 0;
forawait (const acct of paginate<Account>("/pc/rest/v1/accounts?pageSize=100")) {
awaitindexAccount(acct);
total++;
}
console.log(`indexed ${total} accounts`);
paginate() follows links.next.href until exhausted; the caller cannot accidentally truncate at page 1.
Error Handling
Error
Cause
Solution
409 Conflict on PATCH/PUT
stale checksum — another writer mutated the resource between your GET and PATCH
retry the outer helper (re-GET + re-mutate); retrying the PATCH alone re-uses the stale checksum and will 409 again
429 Too Many Requests
tenant quota exceeded
honour Retry-After; if it recurs, the client is missing a token-bucket layer or another integration shares the tenant quota
400 Bad Request with errors[].type === "invalid-attribute"
validation failure on a field
inspect errors[].attributes for the offending path; do not blanket-retry
422 Unprocessable Entity with errors[].type === "rule-violation"
Gosu business rule rejected the payload
not a transport failure — surface userMessage to the caller, do not retry
502/503/504
transient gateway or upstream blip
retry with backoffFor() jitter, max 3 attempts
Duplicate POST when Idempotency-Key is omitted or per-attempt
client treated each retry as a new logical operation
generate the key once per logical operation, reuse across retries
Truncated dataset from a paginating endpoint
caller treated first page as complete
replace ad-hoc pagination with the paginate() generator
userMessage lost in logs
error wrapper stringified the body and discarded structure
use GwError and log .body.errors separately
For a deeper reference on Cloud API request shapes, the batch endpoint, the included parameter for N+1 elimination, and HTTP/2 connection pooling, see implementation guide and API reference.
See Also
guidewire-install-auth — token provider, scope hardening, secret rotation; this skill consumes getToken() from there
guidewire-core-workflow-a — applies these patterns to the PolicyCenter account → submission → quote → bind pipeline
guidewire-core-workflow-b — applies these patterns to the ClaimCenter FNOL → reserve → settle pipeline
guidewire-observability-and-incident-response — interpretation of 409/429/5xx signals in production dashboards
