# OpenAI official SDKs — atlas

Status: Python openai 3.16.2 and Node openai 7.18.0 (7.19.0 in the downloaded package.json) are installed here; their defaults below were read from the installed source (LIVE_VERIFIED / sdk_types) and webhooks.unwrap was executed offline. .NET, Java, Go, Ruby, CLI and the Agents SDK are DOCUMENTED from the libraries page (UNVERIFIED). Sources: Libraries & CLI · Admin APIs guide (SDK versions) · Error codes → Python library error types · Rate limits → SDK retries · Webhooks guide · SDK surfaces sources/openai/openapi/{python,node}-sdk-api.md · installed sources .venv/lib/python3.12/site-packages/openai/*, node_modules/openai/*. Last verified: 2026-09-18. Machine-readable: generated/fragments/sdks/openai-sdks.json (9 records).

# 1. Matrix

# 2. Python (openai 3.16.2) — verified details

from openai import OpenAI, AsyncOpenAI
client = OpenAI(                       # every argument optional
    api_key=...,                       # OPENAI_API_KEY
    admin_api_key=...,                 # OPENAI_ADMIN_KEY  → client.admin.*
    organization=..., project=...,     # OPENAI_ORG_ID / OPENAI_PROJECT_ID
    webhook_secret=...,                # OPENAI_WEBHOOK_SECRET → client.webhooks.unwrap
    workload_identity=...,             # WIF subject-token provider (mutually exclusive with api_key)
    base_url=...,                      # OPENAI_BASE_URL (e.g. https://eu.api.openai.com/v1)
    timeout=600.0, max_retries=2, default_headers={...}, http_client=httpx.Client(...))

• Constants (openai/_constants.py): DEFAULT_TIMEOUT = httpx.Timeout(timeout=600, connect=5.0), DEFAULT_MAX_RETRIES = 2, INITIAL_RETRY_DELAY = 0.5, MAX_RETRY_DELAY = 8.0, connection pool 1000 / 100 keep-alive.
• Retry logic (_base_client.py): retries connection errors, 408, 409, 429, ≥ 500; reads retry-after-ms then Retry-After (seconds or HTTP-date), refuses to wait above 60 s; x-should-retry header wins. client.with_options(max_retries=0, timeout=30) per call.
• Errors: openai.APIError → APIStatusError (BadRequestError 400, AuthenticationError 401, PermissionDeniedError 403, NotFoundError 404, ConflictError 409, UnprocessableEntityError 422, RateLimitError 429, InternalServerError ≥ 500 incl. 503) plus APIConnectionError, APITimeoutError, InvalidWebhookSignatureError. Attributes: status_code, code, param, type, body, request_id, response.
• Raw/streamed responses: client.responses.with_raw_response.create(...) → .headers, .parse(); client.files.with_streaming_response.content(id).
• Pagination classes: SyncPage, SyncCursorPage, SyncConversationCursorPage, SyncNextCursorPage (+ async twins) — iterate directly, or .has_next_page() / .get_next_page() / .iter_pages().
• Streaming helpers: client.responses.stream(...) (context manager, typed events, get_final_response()), client.chat.completions.stream(...), client.beta.chat.completions.parse(...) for structured outputs; Realtime client.realtime.connect(model=...); openai.lib.streaming.
• Types: Pydantic models in openai.types.*; params as TypedDicts (openai.types.responses.response_create_params); openai.NOT_GIVEN.
• Webhooks: client.webhooks.unwrap(payload, headers, *, secret=None) → typed event union; verify_signature(payload, headers, *, secret=None, tolerance=300); implementation openai/lib/_webhooks.py (HMAC-SHA256, whsec_ base64 secret, v1, signatures, ±300 s).
• Admin: OpenAI(admin_api_key=…).admin.organization.* (see docs/openai/admin-api.md); Admin key is sent for routes whose OpenAPI security is AdminApiKeyAuth.
• Azure: AzureOpenAI(api_version=..., azure_endpoint=..., api_key=... | azure_ad_token_provider=...); openai.lib.azure, plus openai.lib.bedrock shim.
• Logging: OPENAI_LOG=debug.

# 3. TypeScript / JavaScript (openai 7.18.0) — verified details

import OpenAI from "openai";
const client = new OpenAI({
  apiKey, adminAPIKey, organization, project, webhookSecret, workloadIdentity, baseURL,
  timeout: 600_000, maxRetries: 2, defaultHeaders, defaultQuery, fetch, fetchOptions, logLevel: "debug",
});

• OpenAI.DEFAULT_TIMEOUT = 600000 (10 min); maxRetries default 2 with exponential backoff + jitter, retry-after-ms / Retry-After ≤ 60 s, x-should-retry. Per-request: client.responses.create(params, { maxRetries: 0, timeout: 5_000, signal, headers }).
• Node ≥ 22 (engines), ESM + CJS builds, .d.mts types; browsers need dangerouslyAllowBrowser: true.
• APIPromise: await p.withResponse() → { data, response, request_id }; await p.asResponse() → fetch Response; results carry _request_id.
• Pagination: for await (const item of client.fineTuning.jobs.list()); pages expose hasNextPage() / getNextPage().
• Streaming: stream: true → async iterable (for await), stream.controller.abort(); helpers client.responses.stream() with .on(...)/finalResponse(), client.chat.completions.stream(); Zod helpers openai/helpers/zod (zodTextFormat, zodResponseFormat).
• Errors: OpenAI.APIError (status, code, type, param, error, requestID, headers) with subclasses BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, InvalidWebhookSignatureError.
• Webhooks: await client.webhooks.unwrap(rawBody, headers, secret?, tolerance = 300), verifySignature(...); verified identical to the Python scheme in examples/openai/webhooks/offline_test.ts.
• Realtime: openai/realtime/websocket (OpenAIRealtimeWebSocket), openai/realtime/ws; WIF helpers in openai/auth/subject-token-providers; Azure AzureOpenAI from openai; Bedrock shim openai/bedrock.

# 4. Other official clients (documented only)

• .NET: dotnet add package OpenAI; ResponsesClient client = new(key); await client.CreateResponseAsync("gpt-6-astra", "…") (#pragma warning disable OPENAI001); Microsoft's Azure.AI.OpenAI wraps it.
• Java (beta, 4.65.0): OpenAIOkHttpClient.fromEnv(); client.responses().create(params); streaming createStreaming; async client.async(); exceptions OpenAIServiceException → RateLimitException (429), InternalServerException (5xx). Admin: .adminApiKey(...) builder + client.admin().organization()… (≥ 4.34.0).
• Go (beta, v3): openai.NewClient(option.WithAPIKey(...)), client.Responses.New(ctx, responses.ResponseNewParams{...}), errors var apiErr *openai.Error; errors.As(err, &apiErr); admin option.WithAdminAPIKey + client.Admin.Organization… (≥ 3.34.0).
• Ruby: OpenAI::Client.new(api_key:, admin_api_key:, webhook_secret:); client.responses.create(...); client.with_options(data_residency: :eu); OpenAI::Errors::APIError, InvalidWebhookSignatureError; typed webhook events OpenAI::Models::Webhooks::ResponseCompletedWebhookEvent (admin ≥ 0.61.0).
• CLI: brew install openai/tools/openai; openai responses create --model … --input … --raw-output --transform '…' (gjson-style transform); guide docs/libraries/openai-cli.
• Agents SDK: openai-agents (Python) / @openai/agents (TS) — orchestration (agents, tools, handoffs, guardrails, tracing, sandboxes) on top of Responses; use the plain SDK for direct calls.
• Azure libraries: .NET, JS, Java, Go clients maintained by Microsoft, compatible with both Azure OpenAI and the OpenAI API.
• Community: Clojure, Dart, Delphi, Elixir, Kotlin, PHP (openai-php/client), Rust (async-openai), Scala, Swift, Unity, Unreal — unverified by OpenAI.

# 5. Behaviour to remember

1. Both first-party SDKs retry 2× by default — disable (max_retries=0) when you implement your own retry or when measuring error shapes, otherwise a 429/5xx costs three requests.
2. RateLimitError ≠ overload: 503 server_is_overloaded surfaces as InternalServerError; catch both.
3. SDKs never send Idempotency-Key; long generations should use background: true + webhooks/polling rather than raising the 10-minute timeout.
4. _request_id is only populated from x-request-id; edge 404s (unknown URL) have none.
5. Admin routes require admin_api_key / adminAPIKey; passing a project key there yields PermissionDeniedError 403 (AuthenticationError 401 for audit logs) — reproduced in examples/openai/admin/admin_readonly.{py,ts}.