Configuration

All SDK configuration options for TypeScript, Python, and Go.

Each SDK accepts the same core configuration options with language-appropriate naming.

TypeScript

import { PlatformXeClient } from '@caldera/platformxe-sdk';

const px = new PlatformXeClient({
  apiKey: 'pxk_live_your_api_key_here',
  baseUrl: 'https://platformxe.com',
  retries: 2,
  timeout: 10000,
  retryDelay: 1000,
});

Option	Type	Default	Description
apiKey	string	--	Required. Your PlatformXe API key
baseUrl	string	https://platformxe.com	API base URL
retries	number	2	Retries after the first attempt (0 = a single attempt). From @caldera/platformxe-sdk 1.6.0: retries 429, 502/503/504, network errors and timeouts for every method, and 500 only for GET/PUT/DELETE; 401, other 4xx, a POST/PATCH 500, other 5xx and a non-envelope 2xx are not retried. In 1.5.x and earlier every 5xx is retried for every method
timeout	number	10000	Request timeout in milliseconds
retryDelay	number	1000	Base retry delay in milliseconds, doubled on each retry

The TypeScript client has no failOpen option. From @caldera/platformxe-sdk 1.6.0, when a request fails it throws a PlatformXeError (or subclass) for any API error response, JSON or not, and for a timeout. It throws the underlying error for a network failure. A non-JSON body never surfaces as a SyntaxError. In 1.5.x and earlier a non-JSON error body surfaces as a SyntaxError.

Python

from platformxe import PlatformXeClient

client = PlatformXeClient(
    api_key="pxk_live_your_api_key_here",
    base_url="https://platformxe.com",
    retries=2,
    timeout=10.0,
    fail_open=True,
)

Option	Type	Default	Description
api_key	str	--	Required. Your PlatformXe API key
base_url	str	https://platformxe.com	API base URL
retries	int	2	Retries after the first attempt on transport failures (0 = a single attempt). API errors are never retried
timeout	float	10.0	Request timeout in seconds
fail_open	bool	True	After the last attempt fails, return {"error": ..., "_failed": True} instead of raising PlatformXeError. API errors always raise

Go

client := px.NewClient(px.ClientConfig{
    APIKey:   "pxk_live_your_api_key_here",
    BaseURL:  "https://platformxe.com",
    Retries:  2,
    Timeout:  10,
    FailOpen: false,
})

Option	Type	Default	Description
APIKey	string	--	Required. Your PlatformXe API key
BaseURL	string	https://platformxe.com	API base URL
Retries	int	2	Retries after the first attempt. Retries transport failures, 429 and 502/503/504 for every method, and 500 only for GET/HEAD/PUT/DELETE/OPTIONS; a POST/PATCH 500, other 5xx and other 4xx are not retried. 0 is Go's zero value and means "use the default" (2); a negative value means no retries
DisableRetries	bool	false	true forces exactly one attempt, whatever Retries says. Use this to configure zero retries
Timeout	int	10	Request timeout in seconds
FailOpen	bool	false	When the last attempt fails at the transport level, return a {"_failed": true, "error": ...} result with a nil error instead of an error. API errors — any non-2xx, including a retried status still failing after the last retry — always return an error

// Go — no retries: set DisableRetries (Retries: 0 would mean "default")
client := px.NewClient(px.ClientConfig{APIKey: "...", DisableRetries: true})

Common options

apiKey

Your API key, starting with pxk_live_ (production) or pxk_test_ (test). The key is sent as the x-api-key header on every request.

Pass the key explicitly — the SDKs do not read an environment variable for it.

baseUrl

Override the API endpoint. Useful for local development or testing against a staging environment.

// TypeScript
const px = new PlatformXeClient({ apiKey: '...', baseUrl: 'http://localhost:3000' });

# Python
client = PlatformXeClient(api_key="...", base_url="http://localhost:3000")

// Go
client := px.NewClient(px.ClientConfig{APIKey: "...", BaseURL: "http://localhost:3000"})

retries

Number of retries after the first attempt, with exponential backoff (TypeScript: retryDelay doubled per retry; Python and Go: 200 ms doubled per retry).

TypeScript and Go follow the same rule for error statuses: 429, 502, 503 and 504 are retried for every method, and 500 only for the idempotent ones, because PlatformXe answers a handler failure with 500 after side effects may already have landed. The idempotent set differs only because of what each client can send: Go retries a 500 for GET, HEAD, PUT, DELETE and OPTIONS, while the TypeScript client cannot send HEAD or OPTIONS, so its set is GET, PUT and DELETE. Both also retry transport failures. Python retries transport failures only.

The TypeScript behaviour described below is that of @caldera/platformxe-sdk 1.6.0 (SDK MR !5, merging separately). In 1.5.x and earlier every 5xx is retried for every method, and a non-JSON error body surfaces as a SyntaxError. The details per SDK:

• TypeScript retries 429, 502, 503, 504, network errors and timeouts for every method, and 500 only for GET, PUT and DELETE. A 429 is retried on the same backoff; a Retry-After header does not change the delay but is exposed as RateLimitError.retryAfter. PlatformXe answers a handler failure with 500 after side effects may already have landed, so a POST/PATCH 500 is thrown after one attempt, as is any other 5xx. 401 throws AuthenticationError immediately whatever its body. Any other 4xx is thrown immediately: 400 as ValidationError, 404 as NotFoundError, otherwise PlatformXeError. Every non-2xx error carries status, plus code and message from a JSON envelope when the body has one. Otherwise the code is HTTP_<status> and the message is the status text plus, for a text or HTML body, an excerpt of up to 200 characters; a JSON body that is not an envelope is described by its shape only, so a body carrying a key cannot be echoed. A retried status still failing after the last retry throws that PlatformXeError. A 2xx with "success": false throws with the envelope's code; a 2xx whose body is not a JSON { success, data } envelope throws INVALID_RESPONSE immediately.
• Python retries transport failures (connection errors, timeouts) only. Any JSON error response, a 5xx included, raises PlatformXeAPIError immediately. A non-JSON response with a non-success status (for example a gateway's HTML 502 page) also raises PlatformXeAPIError immediately, with code HTTP_<status>: it is not retried and fail_open does not apply. A non-JSON success response raises PlatformXeError, which is handled like a transport failure.
• Go retries transport failures, 429, 502, 503 and 504 for every method, and 500 only for GET, HEAD, PUT, DELETE and OPTIONS, all on the same backoff. A POST/PATCH 500 returns an error after one attempt, as does any other non-2xx. Every non-2xx response — JSON envelope, other JSON such as {"error": "..."}, or a body that is not JSON at all (for example a gateway's HTML 502 page) — returns an *APIError with StatusCode, plus Code and Message from the body when it has them (otherwise HTTP_<status> and the status text). Use errors.As to inspect it. A retried status still failing after the last retry returns that *APIError: FailOpen does not apply. A 2xx with "success": false also returns an *APIError; a 2xx whose body is not JSON returns an unmarshal response error immediately.

In Go, Retries: 0 means "use the default"; set DisableRetries: true for a single attempt.

timeout

Request timeout. If a request takes longer than this, it is aborted and retried (if retries remain).

• TypeScript: milliseconds (timeout: 5000 for 5 seconds)
• Python: seconds (timeout=5.0 for 5 seconds)
• Go: seconds (Timeout: 5 for 5 seconds)

failOpen

Python and Go only (the TypeScript client always throws). When enabled, a request whose retries ran out on a transport failure returns a _failed result instead of raising/returning an error. API error responses are not affected (in Go that includes a retried status still failing after the last retry), and neither is a non-JSON error response such as a proxy's HTML 502 page: Python raises PlatformXeAPIError and Go returns an *APIError. Go decides on the last attempt only: a 503 followed by a transport failure returns the _failed result, and a transport failure followed by a 503 returns the *APIError. Python defaults to True, Go to false.

# Python (fail_open=True, the default)
result = client.get("/api/health")
if result.get("_failed"):
    print("PlatformXe unreachable:", result["error"])

// Go (FailOpen: true)
result, err := client.Get("/api/health", nil)
if err != nil {
    fmt.Println(err) // an API error, or FailOpen is false
} else if failed, _ := result["_failed"].(bool); failed {
    fmt.Println("PlatformXe unreachable:", result["error"])
}