# SDK Overview: [Product name] SDKs

> Landing page for the official client libraries of an API: which
> languages are supported and at what status, how to install each SDK,
> configure authentication, make a first call, handle errors, retries,
> timeouts and pagination, turn on logging, and which versioning and
> support policy applies, with links to the generated reference for each
> language. It assumes the API is described with the OpenAPI
> Specification 3.2.1 (3.1.x also widely used) and that SDK releases
> follow Semantic Versioning 2.0.0. Replace every `[bracketed]` value and
> every row marked *Example*.

<!--
Guidance: How to use this template
- This page is the entry point for developers who choose an SDK. It is
  shorter than the Developer Guide (`docs/developer-guide`) and more
  specific than the product Quickstart (`docs/quickstart`). The method
  by method detail belongs in the generated reference (section 12).
- Fill section 2 (supported languages) first. Every later section shows
  one code sample per supported language, so the matrix decides how many
  samples you maintain.
- Keep samples short, runnable and tested in CI against the sandbox. A
  sample that does not run is worse than no sample.
- Show the same task in every language, with the same names, so readers
  can compare and so reviewers can spot gaps.
- The worked example is fictional: the Corvid Commerce Orders API and
  its SDKs. Package names such as `corvid-commerce` are illustrative.
- Related documents: API Overview (`docs/api-overview`), API Reference
  (`dev/api-reference`), API Changelog (`docs/api-changelog`),
  Deprecation Notice (`docs/deprecation-notice`), Migration Guide
  (`docs/migration-guide`), Library README (`dev/library-readme`),
  Versioning and Release Policy (`dev/versioning-release-policy`),
  Troubleshooting (`docs/troubleshooting`), Known Issues
  (`docs/known-issues`).
-->

## Document control

<!-- Guidance: Record which SDK releases this page describes. Update it with every major SDK release and at least once per quarter, because runtime support windows move even when the SDK does not. -->

| Field | Value |
|---|---|
| Document ID | [SDK-OVW-001] |
| Product and API | [Corvid Commerce Orders API v2] |
| SDK releases described | [Python 5.3.0, TypeScript 5.3.0, Java 5.3.0, Go 5.3.0, .NET 5.3.0] |
| API description | [OpenAPI 3.2.1 document URL] |
| Generator and version (if generated) | [Generator name and version, or "handwritten"] |
| Version | [1.0] |
| Status | [Draft / Published] |
| Owner | [@sdk-lead] |
| Approvers/reviewers | [@api-product-owner], [@developer-relations], [@technical-writer], [@security-reviewer] |
| Last updated | YYYY-MM-DD |
| Classification | Public |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| SDK lead | [@name] | [Approve / Reject] | YYYY-MM-DD |
| API product owner | [@name] | [Decision] | YYYY-MM-DD |
| Security reviewer (auth and logging sections) | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Published with SDK 5.0.0 for API v2 |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added .NET SDK as Beta; Python 3.10 removed from the matrix after its upstream end of life |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [About the SDKs](#1-about-the-sdks)
2. [Supported languages](#2-supported-languages)
3. [Install](#3-install)
4. [Authentication and configuration](#4-authentication-and-configuration)
5. [Make your first call](#5-make-your-first-call)
6. [Handle errors](#6-handle-errors)
7. [Retries and timeouts](#7-retries-and-timeouts)
8. [Pagination](#8-pagination)
9. [Logging and debugging](#9-logging-and-debugging)
10. [Webhooks and events](#10-webhooks-and-events)
11. [Versioning and support policy](#11-versioning-and-support-policy)
12. [Reference and resources](#12-reference-and-resources)
13. [Glossary and references](#13-glossary-and-references)

## 1. About the SDKs

<!-- Guidance: Tell readers in a few sentences what the SDKs do for them compared with calling the HTTP API directly, and how the SDKs are built. Questions: are they generated from the OpenAPI document, handwritten, or both? Are they the only supported clients? Pitfall: implying the SDK is required when raw HTTP is fully supported. -->

The [Product name] SDKs are official client libraries for the
[API name]. They handle authentication, request signing, serialisation,
retries with backoff, pagination and typed errors, so that your code
deals with orders and customers rather than with HTTP details.

*Example:* The SDKs are generated from the public OpenAPI 3.2.1
description of the Orders API and then extended with handwritten helpers
for pagination, retries and webhook signature checks. Generated code and
helpers ship together in one package per language. Because the method
names come from the `operationId` values in the description, a renamed
operation is a breaking change for SDK users; the API Changelog
(`docs/api-changelog`) flags such changes.

You can always call the HTTP API directly. Every SDK feature described
here maps to documented API behaviour, so the API Overview
(`docs/api-overview`) and the API Reference (`dev/api-reference`) remain
the contract.

| You want to | Use |
|---|---|
| Build an integration in a supported language | The SDK for that language |
| Use a language without an SDK | The HTTP API, or a community library at your own risk |
| Explore the API without code | The API reference "Try it" console or an HTTP client |
| Receive events | The webhook helpers in section 10 |

## 2. Supported languages

<!-- Guidance: One row per SDK, with the minimum runtime, package name and registry, latest version, status and reference link. Questions: which runtimes are still supported upstream? What do the status values promise? Pitfall: listing a runtime version that its own maintainers no longer support. -->

| Language | Minimum runtime | Package | Registry | Latest | Status | Reference |
|---|---|---|---|---|---|---|
| Python *(Example)* | [Python 3.11] | `corvid-commerce` | PyPI | 5.3.0 | GA | [Python reference] |
| TypeScript and JavaScript *(Example)* | [Node.js 22 LTS] | `@corvid/commerce` | npm | 5.3.0 | GA | [TypeScript reference] |
| Java *(Example)* | [Java 17] | `com.corvid:commerce` | Maven Central | 5.3.0 | GA | [Java reference] |
| Go *(Example)* | [Go 1.26] | `corvid.example/commerce/v5` | Go module proxy | v5.3.0 | GA | [Go reference] |
| C# and .NET *(Example)* | [.NET 10 LTS] | `Corvid.Commerce` | NuGet | 5.3.0-beta.2 | Beta | [.NET reference] |
| [Language] | [Runtime] | [Package] | [Registry] | [x.y.z] | [GA / Beta / Maintenance / Deprecated] | [Link] |

Runtime minimums in this table are examples. Set yours from the support
schedule that each runtime publishes, and review the table when a runtime
version reaches its upstream end of life.

*Example:* The bracketed minimums were all supported upstream when this
template was checked on 2026-10-24 (endoflife.date and the vendors' own
pages): Python 3.11 until 2027-10-31, Node.js 22 LTS until 2027-04-30,
Java 17 (Eclipse Temurin builds) until at least 2027-10-31, Go 1.26 until
two newer Go major releases ship, and .NET 10 LTS until 2028-11-14.
Node.js 20 (2026-04-30), Python 3.10 (October 2026) and Go 1.24 had
already reached end of life, and .NET 8 ends on 2026-11-10, which is why
they are not used. Node.js 22, Python 3.11 and Java 17 reach end of life
during 2027, so plan when the SDKs drop them under section 11.3.

### 2.1 Status values

| Status | What it promises |
|---|---|
| GA | Covered by the support policy in section 11; breaking changes only in a major release |
| Beta | Feature complete for common use; breaking changes possible in minor releases with a changelog entry |
| Maintenance | Security and severe defect fixes only; no new API features |
| Deprecated | Will reach end of support on a stated date; see the Deprecation Notice |

### 2.2 Feature coverage

| Feature | Python | TypeScript | Java | Go | .NET |
|---|---|---|---|---|---|
| All v2 operations *(Example)* | Yes | Yes | Yes | Yes | Yes |
| Automatic pagination iterators *(Example)* | Yes | Yes | Yes | Yes | Yes |
| Webhook signature verification *(Example)* | Yes | Yes | Yes | Yes | No (planned) |
| Async or non-blocking client *(Example)* | Yes | Yes (native) | Yes | n/a (goroutines) | Yes |
| [Feature] | [Yes / No] | [Yes / No] | [Yes / No] | [Yes / No] | [Yes / No] |

## 3. Install

<!-- Guidance: Show the standard package manager command for each language, and how to pin a version. Questions: are packages signed or published with provenance attestations, and how can readers verify them? Pitfall: install commands that pull the latest major version silently, so a later reinstall breaks the build. -->

Install the SDK with your language's package manager and pin the major
version, so that a new major release never arrives without a code change.

```bash
# Python
pip install "corvid-commerce>=5.3,<6"

# TypeScript and JavaScript
npm install @corvid/commerce@^5.3.0

# Go
go get corvid.example/commerce/v5@v5.3.0

# .NET
dotnet add package Corvid.Commerce --version 5.3.0-beta.2
```

```xml
<!-- Java (Maven) -->
<dependency>
  <groupId>com.corvid</groupId>
  <artifactId>commerce</artifactId>
  <version>5.3.0</version>
</dependency>
```

**Verify what you install.** *Example:* Every release is published from
CI with a provenance attestation, and a software bill of materials is
attached to each release on the source repository. Check them in your
supply chain tooling before you upgrade.

**Dependencies.** Keep the SDK's own dependencies small. List any that a
reader may need to know about, such as an HTTP client that conflicts with
a common framework version. *Example:* The Python SDK depends on one HTTP
library and one typing helper; the Go SDK uses the standard library only.

## 4. Authentication and configuration

<!-- Guidance: Show how to give the SDK its credentials and settings, and in what order sources are read. Questions: which auth methods does the API support (API key, OAuth 2.0 client credentials, token exchange)? Where should secrets live? Pitfall: samples that paste a key into source code; readers copy samples verbatim. -->

### 4.1 Credentials

*Example:* The Orders API uses secret API keys for server-side code and
OAuth 2.0 client credentials for partner apps. The SDKs read the key from
the environment variable `CORVID_API_KEY` when you do not pass one
explicitly.

Never put a secret key in source code, a mobile app, a browser bundle or
a public repository. Load it from a secrets manager or the environment at
runtime, give each environment its own key, and rotate keys on a
schedule and whenever someone with access leaves. If a key is exposed,
revoke it in the dashboard first and investigate afterwards.

### 4.2 Configuration options

| Option | Environment variable | Default | Description |
|---|---|---|---|
| `api_key` *(Example)* | `CORVID_API_KEY` | none (required) | Secret key for server-side use |
| `base_url` *(Example)* | `CORVID_BASE_URL` | `https://api.example.com` | Override for the sandbox or a regional endpoint |
| `timeout` *(Example)* | `CORVID_TIMEOUT` | 30 seconds | Total time per request attempt |
| `max_retries` *(Example)* | `CORVID_MAX_RETRIES` | 2 | Retries after the first attempt |
| `api_version` *(Example)* | `CORVID_API_VERSION` | Pinned per SDK major version | API version the SDK sends |
| `log_level` *(Example)* | `CORVID_LOG` | `warning` | SDK log verbosity |
| `telemetry` *(Example)* | `CORVID_TELEMETRY` | `off` | Optional aggregate SDK usage reporting, off unless you enable it |
| [Option] | [Variable] | [Default] | [Description] |

**Precedence.** *Example:* A value passed in code wins over an
environment variable, which wins over the default. State this order
explicitly, because readers debugging a wrong endpoint need to know where
the value came from.

**Telemetry.** If an SDK can report anything about its own use, keep it
off by default, report aggregate counts only (SDK version, runtime
version, operation name), never send request or response content,
credentials or personal data, and document how to confirm that it is off.

### 4.3 Create a client

```python
# Python
import os
from corvid_commerce import Client

client = Client(api_key=os.environ["CORVID_API_KEY"])
```

```typescript
// TypeScript
import { Client } from "@corvid/commerce";

const client = new Client({ apiKey: process.env.CORVID_API_KEY });
```

```go
// Go
client := commerce.NewClient(commerce.WithAPIKey(os.Getenv("CORVID_API_KEY")))
```

Create one client per process and reuse it. The client holds a
connection pool; creating a client per request wastes connections and
slows every call.

## 5. Make your first call

<!-- Guidance: Show the smallest useful call in every language, against the sandbox, with the expected output. Questions: does the call work with a brand-new sandbox account? Pitfall: a first call that needs data the reader has not created yet. -->

Use a sandbox key for this step. The sandbox starts with sample orders,
so the call returns data straight away.

```python
# Python: list the five most recent orders
for order in client.orders.list(limit=5):
    print(order.id, order.status, order.total_amount.value, order.total_amount.currency)
```

```typescript
// TypeScript: list the five most recent orders
for await (const order of client.orders.list({ limit: 5 })) {
  console.log(order.id, order.status, order.totalAmount.value, order.totalAmount.currency);
}
```

```java
// Java: list the five most recent orders
for (Order order : client.orders().list(ListOrdersParams.builder().limit(5).build())) {
    System.out.println(order.getId() + " " + order.getStatus());
}
```

Expected output (*Example*, sandbox data):

```text
ord_9f3k2 paid 120.00 EUR
ord_9f3k1 partially_shipped 48.50 EUR
ord_9f3jz shipped 15.99 EUR
```

If you see an authentication error, check that you used a sandbox key
with the sandbox base URL. Mixing a sandbox key with the production URL
is the most common first-call failure.

**Next steps.** Create an order with an idempotency key, then subscribe
to the `order.updated` event type (AsyncAPI operation `orderUpdated`).
The Quickstart (`docs/quickstart`) walks
through both.

## 6. Handle errors

<!-- Guidance: List the error types the SDK raises or returns, how they map to HTTP status codes and API error codes, and what the reader should do for each. Questions: is the API error code and request ID always available on the error? Pitfall: catching every exception and retrying, which hides bugs and repeats non-idempotent writes. -->

Every SDK maps API errors to typed errors with the same fields: the HTTP
status, the API error code, a human-readable message and the request ID.
Log the request ID; support needs it to trace a call.

| Error type | HTTP status | Typical cause | What to do |
|---|---|---|---|
| `AuthenticationError` *(Example)* | 401 | Missing, revoked or wrong-environment key | Check the key and base URL; do not retry |
| `PermissionError` *(Example)* | 403 | Key lacks the scope | Request the scope; do not retry |
| `NotFoundError` *(Example)* | 404 | Unknown ID or wrong account | Check the ID; do not retry |
| `ValidationError` *(Example)* | 400, 422 | Invalid input; field errors listed | Fix the input; do not retry |
| `ConflictError` *(Example)* | 409 | Concurrent update or idempotency conflict | Re-read and decide; retry only with the same idempotency key |
| `RateLimitError` *(Example)* | 429 | Too many requests | Retried automatically; slow down if it persists |
| `ApiError` (server) *(Example)* | 500 to 599 | Temporary server problem | Retried automatically for safe and idempotent calls |
| `ConnectionError` *(Example)* | none | Network failure or timeout | Retried automatically; check connectivity if it persists |
| `ApiVersionSunsetError` *(Example)* | 410 | API version retired | Upgrade the SDK; see the Deprecation Notice |

```python
from corvid_commerce import errors

try:
    order = client.orders.create(lines=[...], idempotency_key=key)
except errors.ValidationError as e:
    for field_error in e.field_errors:
        print(field_error.field, field_error.message)
except errors.ApiError as e:
    log.error("Orders API error %s (request %s)", e.code, e.request_id)
    raise
```

Do not parse error messages; they can change. Branch on the error type
and the error code, which are part of the contract.

## 7. Retries and timeouts

<!-- Guidance: State exactly which calls the SDK retries, how often, with what backoff, and how readers change it. Questions: does the SDK retry writes? Does it honour Retry-After? Pitfall: a default timeout so long that a hung request blocks a web worker for minutes. -->

### 7.1 Retries

*Example:* The SDKs retry a failed request up to 2 times after the first
attempt when the failure is a connection error, a timeout, `429` or a
`5xx` status. They wait with exponential backoff and random jitter, and
they honour the `Retry-After` header when the API sends one.

The SDKs retry a write only when it is safe: `GET`, `PUT` and `DELETE`
are idempotent by definition, and `POST` is retried only when the
request carries an idempotency key. The SDKs add a key automatically to
`POST` calls when you do not supply one, and reuse it on every retry of
that call. Supply your own key when you might repeat the whole operation
later, for example after a process restart.

```python
# Override retries for one call
client.orders.list(limit=100, max_retries=5)

# Turn off retries for a client
client = Client(api_key=key, max_retries=0)
```

### 7.2 Timeouts

| Timeout | Default | Change it when |
|---|---|---|
| Connect *(Example)* | 5 seconds | Your network has high latency to the API region |
| Per attempt *(Example)* | 30 seconds | You call bulk operations that take longer |
| Total including retries *(Example)* | 90 seconds | You run inside a request handler with its own deadline |

Set timeouts shorter than the deadline of the code that calls the SDK. A
web request that must answer in 10 seconds cannot wait 90 seconds for a
retried API call; pass a shorter timeout or use the language's
cancellation mechanism (context in Go, `AbortSignal` in TypeScript).

## 8. Pagination

<!-- Guidance: Show how to iterate through all results without handling cursors by hand, and how to page manually when needed. Questions: is pagination cursor-based? What is the maximum page size? Pitfall: loading every page into memory before processing. -->

*Example:* List operations return pages of up to 100 items with a cursor
for the next page. The SDK list methods return an iterator that fetches
the next page only when you reach the end of the current one, so you can
process large result sets with constant memory.

```python
# Automatic: iterate every order updated since a timestamp
for order in client.orders.list(updated_since="2026-10-01T00:00:00Z"):
    process(order)

# Manual: one page at a time, for example to checkpoint the cursor
page = client.orders.list_page(limit=100)
while page:
    save_checkpoint(page.next_cursor)
    handle(page.items)
    page = page.next_page()
```

```go
// Go: automatic iteration
iter := client.Orders.List(ctx, &commerce.ListOrdersParams{Limit: 100})
for iter.Next() {
    process(iter.Current())
}
if err := iter.Err(); err != nil {
    return err
}
```

Store the cursor, not a page number, if you resume a long synchronisation
later. Cursors stay valid while new orders are created, and they expire
after [24 hours] *(Example)*. For incremental synchronisation, filter by
update time instead of listing everything again.

## 9. Logging and debugging

<!-- Guidance: Show how to see what the SDK sends and receives, and what it never logs. Questions: are credentials and personal data redacted at every log level? Can logs go to the application's own logger? Pitfall: a debug mode that prints authorisation headers and customer addresses into shared logs. -->

The SDKs log through the standard logging facility of each language, so
SDK messages appear in your existing log pipeline.

| Level | What is logged *(Example)* |
|---|---|
| `error` | Final failure of a request after retries, with error type, code and request ID |
| `warning` | Deprecation warnings, retries that hit their limit, sunset dates approaching |
| `info` | One line per request: method, path template, status, duration, attempt number, request ID |
| `debug` | Headers and bodies, with redaction applied |

**Redaction.** *Example:* At every level, the SDK replaces the
`Authorization` header, API keys, webhook secrets and fields marked as
sensitive in the OpenAPI document (such as email, phone and address)
with `[REDACTED]`. Use `debug` only in development or for a short,
controlled investigation, and never forward debug logs to third parties.

**Request IDs.** Every response carries a request ID (*Example:* header
`X-Request-Id`), and every SDK error exposes it. Include it when you
contact support.

**Deprecation warnings.** When the API returns a `Deprecation` header
(RFC 9745) or a `Sunset` header (RFC 8594), the SDK logs one warning per
operation per process with the dates and the documentation link. Treat
these warnings as work items; the Deprecation Notice
(`docs/deprecation-notice`) explains what to do.

```bash
# Turn on info logging for one run
CORVID_LOG=info python sync_orders.py
```

## 10. Webhooks and events

<!-- Guidance: If the API sends webhooks, show how the SDK verifies and parses them. Questions: which signature scheme? How is replay prevented? Pitfall: parsing the JSON body before verifying the signature, or verifying against a re-serialised body instead of the raw bytes. -->

*Example:* The SDKs include a helper that verifies the signature of a
webhook delivery and returns a typed event. Verify against the raw
request body bytes and the signature header, with the endpoint secret
from your dashboard. The helper rejects deliveries whose timestamp is
older than five minutes, to limit replay.

```typescript
// TypeScript (framework-neutral)
const event = client.webhooks.constructEvent(rawBody, signatureHeader, endpointSecret);
if (event.type === "order.updated") {
  await handleOrderUpdate(event.data);
}
```

Respond with a `2xx` status quickly and do the work asynchronously;
deliveries that time out are retried and can arrive more than once, so
make your handler idempotent by event ID. For the delivery model, see the
Webhook Delivery system design (`system-design/design-webhook-delivery`).

## 11. Versioning and support policy

<!-- Guidance: Tell readers what each SDK version number promises, how SDK versions relate to API versions, and how long each major version is supported. Questions: is the support window tied to API sunset dates? Which runtime versions are dropped and when? Pitfall: dropping a runtime version in a minor release, which breaks builds without a major version change. -->

### 11.1 Version numbers

The SDKs follow Semantic Versioning 2.0.0:

- **Major** (for example 5.0.0): breaking changes to the SDK interface,
  a new default API version, or removal of a supported runtime version.
- **Minor** (for example 5.3.0): new API operations and fields, new
  helpers, and deprecations of SDK methods.
- **Patch** (for example 5.3.1): fixes that do not change the interface.

*Example:* SDK major 5 targets Orders API v2; SDK major 4 targets v1. An
SDK minor release never changes the API version it sends by default.

### 11.2 Support windows

| SDK major | Status | Supported until | Notes |
|---|---|---|---|
| 5.x *(Example)* | Active | At least 12 months after 6.0.0 is released | New features and fixes |
| 4.x *(Example)* | Maintenance | 2027-11-17 (API v1 sunset) | Security and severe defect fixes only |
| 3.x *(Example)* | End of support | 2025-12-31 | No fixes |
| [Major] | [Active / Maintenance / End of support] | YYYY-MM-DD | [Notes] |

### 11.3 Runtime support

*Example:* An SDK supports every runtime version that is supported
upstream when the SDK major version is released. When a runtime version
reaches its upstream end of life, the next SDK minor release may stop
testing against it, and the next SDK major release removes it. Removal is
announced in the API Changelog (`docs/api-changelog`) at least
[90 days] ahead.

### 11.4 Upgrading

Read the SDK release notes for every major version you cross. Upgrade
one major version at a time in a branch, run your tests against the
sandbox, and watch for deprecation warnings in section 9 before you
deploy. The Migration Guide (`docs/migration-guide`) covers API-level
changes; each SDK repository carries an upgrade guide for SDK-level
changes.

## 12. Reference and resources

<!-- Guidance: Link every generated reference, source repository, changelog and support channel. Questions: does each link point to the reference for the latest release, with older versions reachable? Pitfall: a reference site that shows only the newest version while readers are pinned to an older one. -->

| Resource | Python | TypeScript | Java | Go | .NET |
|---|---|---|---|---|---|
| Generated reference | [Link] | [Link] | [Link] | [Link] | [Link] |
| Source repository | [Link] | [Link] | [Link] | [Link] | [Link] |
| SDK release notes | [Link] | [Link] | [Link] | [Link] | [Link] |
| Examples folder | [Link] | [Link] | [Link] | [Link] | [Link] |
| Issue tracker | [Link] | [Link] | [Link] | [Link] | [Link] |

Other resources:

- API Reference (`dev/api-reference`) and the OpenAPI description
  document, the source of truth for operations and fields.
- API Changelog (`docs/api-changelog`) for API-level changes and the SDK
  versions that include them.
- Known Issues (`docs/known-issues`) for open problems and workarounds.
- Troubleshooting (`docs/troubleshooting`) for common errors.
- Support: [support channel], [community forum], [status page].

**Reporting a bug.** Open an issue in the SDK repository with the SDK
version, runtime version, a minimal code sample and the request ID.
Remove keys and personal data before you post. Report security issues
privately as described in the repository security policy.

## 13. Glossary and references

<!-- Guidance: Define SDK terms the way this page uses them. Pitfall: using "version" without saying whether it means the SDK version or the API version. -->

### 13.1 Glossary

| Term | Meaning on this page |
|---|---|
| SDK | Official client library for one programming language |
| API version | Version of the HTTP API contract the SDK calls, for example v2 |
| SDK version | Semantic version of the SDK package, for example 5.3.0 |
| Generated code | Code produced from the OpenAPI description by a generator |
| Idempotency key | Client-supplied value that lets the API recognise a repeated write |
| Cursor | Opaque value that marks a position in a paginated list |
| Backoff with jitter | Increasing, randomised wait between retries |
| Request ID | Identifier of one API request, used to trace it in support |
| Sandbox | Test environment with sample data and separate keys |

### 13.2 References

| Reference | Version or date | Use in this template |
|---|---|---|
| OpenAPI Specification, spec.openapis.org | 3.2.1, 2026-09-10 (Apache License 2.0) | Source description for generated SDKs; `operationId` drives method names |
| Semantic Versioning, semver.org | 2.0.0 (CC BY 3.0) | SDK version number meaning |
| RFC 9745, The Deprecation HTTP Response Header Field | Standards Track, March 2025 | Deprecation warnings in SDK logs |
| RFC 8594, The Sunset HTTP Header Field | Informational, May 2019 | Sunset warnings in SDK logs |
| RFC 9110, HTTP Semantics | June 2022 | Idempotent methods, `Retry-After`, status codes |
| The Good Docs Project, `sdk-overview` template, gitlab.com/tgdp/templates | Repository checked 2026-10-24 (MIT-0) | Inspiration for the section list only; no text reused |
| Runtime support schedules: endoflife.date, nodejs.org, devguide.python.org, go.dev, dotnet.microsoft.com, adoptium.net | Checked 2026-10-24 | Example minimum runtime versions in section 2 |

## Standard and licence note

Based on the OpenAPI Specification 3.2.1 (OpenAPI Initiative,
https://spec.openapis.org/oas/v3.2.1.html, Apache License 2.0) as the
source for generated clients, on Semantic Versioning 2.0.0 for version
numbers, and on IETF RFC 9745, RFC 8594 and RFC 9110 for deprecation
signals, retries and status codes. The section list was informed by the
`sdk-overview` template of The Good Docs Project (MIT-0); no text from it
is reused. Corvid Commerce, its package names, versions and code samples
are fictional. This template is original text written for this
collection. Check the current specification versions and each runtime's
own support schedule before use. Template licence: MIT.