Configure the client

The defaults are chosen to be right for most callers, so you can construct a client with nothing but an API key. This page covers the handful of settings worth changing deliberately — and the two lifetime rules that matter in production.

The defaults

Setting	Default	Change it when
Base URL	the hosted Pagr API	You’re targeting another instance (a local dev server, a private deployment).
Request timeout	30 s	A single render or download legitimately takes longer. Prefer a per-call override.
Max retries	2 (3 attempts) on idempotent GETs	You want retries off (0), or you’re behind a flaky network and want more.
API key	— (required)	Rotation, or per-tenant keys in a multi-tenant service.

Backoff internals — 500 ms first step, 8 s ceiling, 60 s Retry-After ceiling, full jitter — are the same in every SDK and are not intended as tuning surface. See Handle errors and retries.

Constructing a client

Python

from pagr import PagrApiClient

# Simplest form — hosted API, 30s timeout, 2 retries
async with PagrApiClient("pagr_prod_xxxxxxxx") as client:
    ...

# Full control
async with PagrApiClient(
    api_key="pagr_prod_xxxxxxxx",
    base_url="http://localhost:5110",   # omit for the hosted API
    timeout=60.0,                        # seconds
    max_retries=0,                       # disable retries
) as client:
    ...

# A long-lived singleton, closed on shutdown
client = PagrApiClient("pagr_prod_xxxxxxxx")
try:
    ...
finally:
    await client.aclose()                # releases the connection pool

TypeScript

import { PagrApiClient } from 'pagr';

// Simplest form — hosted API, 30s timeout, 2 retries
const client = new PagrApiClient('pagr_prod_xxxxxxxx');

// Full control
const configured = new PagrApiClient(
  'pagr_prod_xxxxxxxx',
  'http://localhost:5110',      // omit (or pass undefined) for the hosted API
  { timeoutMs: 60_000, maxRetries: 0 },
);

There is nothing to dispose — a fetch-based client holds no pooled connection, so this SDK has no context-manager equivalent by design.

Java

import org.example.PagrApiClient;
import org.example.internal.PagrClientConfig;
import java.time.Duration;

// Simplest form — hosted API, defaults
try (PagrApiClient client = new PagrApiClient("pagr_prod_xxxxxxxx")) {
    ...
}

// Another instance
try (PagrApiClient client =
         new PagrApiClient("pagr_prod_xxxxxxxx", "http://localhost:5110")) {
    ...
}

// Full control — note builder(apiKey, baseUrl) takes both
PagrClientConfig config = PagrClientConfig
    .builder("pagr_prod_xxxxxxxx", PagrClientConfig.DEFAULT_BASE_URL)
    .connectTimeout(Duration.ofSeconds(10))
    .requestTimeout(Duration.ofSeconds(60))
    .maxRetries(0)
    .build();

try (PagrApiClient client = new PagrApiClient(config)) {
    ...
}

Java is the only SDK that separates connect timeout (default 10 s) from request timeout (default 30 s).

C#

using Pagr.Sdk;

// Simplest form — hosted API, defaults
using var client = new PagrApiClient("pagr_prod_xxxxxxxx");

// Full control
using var configured = new PagrApiClient(
    "pagr_prod_xxxxxxxx",
    baseUrl: "http://localhost:5110",   // pass null for the hosted API
    options: new PagrClientOptions
    {
        Timeout = TimeSpan.FromSeconds(60),
        MaxRetries = 0,
    });

The client owns a single pooled HttpClient. Register it as a singleton; never new one per request.

Ruby

require "pagr"

# Simplest form — hosted API, defaults
client = Pagr::Client.new("pagr_prod_xxxxxxxx")

# Full control
client = Pagr::Client.new(
  "pagr_prod_xxxxxxxx",
  base_url: "http://localhost:5110",   # omit for the hosted API
  timeout: 60,                          # seconds
  max_retries: 0,
)

# The block form is scoping sugar, not resource cleanup
Pagr::Client.new(ENV.fetch("PAGR_API_KEY")) do |c|
  c.render(template_id, data)
end

There is nothing to dispose — Faraday’s connection isn’t a pooled resource tied to one Client instance, so the block form scopes the variable and nothing more.

C++

#include "pagr/PagrApiClient.hpp"

// Simplest form — hosted API, defaults
pagr::PagrApiClient client("pagr_prod_xxxxxxxx");

// Another instance — note the order is (base_url, api_key)
pagr::PagrApiClient local("http://localhost:5110", "pagr_prod_xxxxxxxx");

// Full control, via C++20 designated initialisers
pagr::PagrApiClient configured({
    .base_url = "http://localhost:5110",
    .api_key = "pagr_prod_xxxxxxxx",
    .timeout = std::chrono::seconds(60),
    .max_retries = 0,
});

Watch the two-argument constructor: it is (base_url, api_key), not (api_key, base_url). The single-argument form takes the key.

cURL

# There's no client to configure — set the base URL and header per request.
export PAGR_BASE_URL="https://api.pagr.eu"
export PAGR_API_KEY="pagr_prod_xxxxxxxx"

curl "$PAGR_BASE_URL/v1/fonts" -H "Authorization: Bearer $PAGR_API_KEY" \
  --max-time 30 --retry 2 --retry-connrefused

--max-time and --retry are the rough equivalents of the SDKs’ timeout and retry settings. Note curl --retry will retry a POST too — the SDKs deliberately don’t.

Never hardcode a key

Read it from an environment variable or a secrets manager. A key grants the ability to render documents and read your organisation’s data — treat it like a password, and keep it server-side. See Authentication.

Per-call timeouts

This is almost always the right knob, and the one most people miss. The client-wide default of 30 seconds is deliberately tight — it fails fast on a stalled connection — but it’s below the server’s 60-second per-document render budget. So a heavy render or a large download can time out on a request that would have succeeded.

Override it for the specific call rather than inflating the default for everything:

Python

# A heavy render, close to the server's 60s budget
result = await client.render(template_id, data, timeout=90)

# A large batch
batch = await client.render_batch(template_id, documents, timeout=300)

# A big PDF over a slow link
pdf = await client.download_document(doc_id, timeout=120)

TypeScript

const result = await client.render(templateId, data, { timeoutMs: 90_000 });
const batch = await client.renderBatch(templateId, documents, { timeoutMs: 300_000 });
const pdf = await client.downloadDocument(docId, { timeoutMs: 120_000 });

Java

// Render calls take the override on RenderOptions
RenderResult result = client.render(templateId, data,
    RenderOptions.builder().timeout(Duration.ofSeconds(90)).build());

BatchRenderResult batch = client.renderBatch(templateId, documents,
    RenderOptions.builder().timeout(Duration.ofMinutes(5)).build());

// Downloads take it as a second argument
byte[] pdf = client.downloadDocument(docId, Duration.ofMinutes(2));

C#

var result = await client.RenderAsync(
    templateId, data, timeout: TimeSpan.FromSeconds(90));

var batch = await client.RenderBatchAsync(
    templateId, documents, timeout: TimeSpan.FromMinutes(5));

var pdf = await client.DownloadDocumentAsync(
    docId, timeout: TimeSpan.FromMinutes(2));

Ruby

result = client.render(template_id, data, timeout: 90)
batch  = client.render_batch(template_id, documents, timeout: 300)
pdf    = client.download_document(doc_id, timeout: 120)

C++

const auto result = client.render(
    template_id, json_data, {.timeout = std::chrono::seconds(90)});

const auto batch = client.render_batch(
    template_id, documents, {.timeout = std::chrono::minutes(5)});

const auto pdf = client.download_document(doc_id, std::chrono::minutes(2));

A timed-out render is not a failed render

The request may have been applied. Because the API has no idempotency keys, the SDKs never retry writes — and neither should you, blindly. Reconcile by listing Documents. See Handle errors and retries.

Cancellation

Every SDK can be told to stop waiting — but each uses its own language’s native primitive rather than an invented Pagr type, and they don’t all cover the same methods.

SDK	Primitive	Where you can pass it
Python	asyncio task cancellation	Nowhere — cancelling the awaiting task is enough, so there’s no SDK parameter
TypeScript	AbortSignal (signal)	render, renderPdf, renderBatch, enqueueBatchRender, getJobStatus, waitForJob, downloadDocument
Java	Cancel the CompletableFuture	The async client (PagrAsyncApiClient); no per-method parameter
C#	CancellationToken	Every public async method
Ruby	A zero-arg cancelled: predicate	wait_for_job only
C++	std::stop_token	wait_for_job / wait_for_job_async only

Two rules hold everywhere:

• A timeout and a cancellation are never confused. The client’s own timeout expiring always raises the SDK’s timeout error; a cancellation you initiated always surfaces as the language’s native cancellation signal, never wrapped in a PagrError. In C++ and Ruby, where there’s no exception to raise, a cancelled wait_for_job instead returns the last polled status — and that status’s done / terminal? is guaranteed false, so you can’t mistake it for a finished job.
• Cancelling breaks a sleep rather than waiting it out. A cancelled wait_for_job stops on the spot instead of sleeping out the remaining poll interval.

What cancellation doesn’t reach

Ruby and C++ cannot abort an HTTP request already on the wire — neither transport offers the hook — so cancellation there covers the poll loop, not a call in flight. In C++, also note that a std::future from an *_async method blocks in its destructor until the call finishes: requesting a stop halts the retry chain, but you must still let the future complete. Dropping it doesn’t abandon the request.

Separately, in all six SDKs, cancelling a wait_for_job does not cancel the render. The job keeps going server-side and the webhook still fires.

Rotating the API key

Every SDK lets you swap the key on a live client, so you don’t have to tear down a connection pool to rotate a credential — or to serve multiple tenants from one client.

Python

client.set_api_key("pagr_prod_new_key")

TypeScript

client.setApiKey('pagr_prod_new_key');

Java

client.setApiKey("pagr_prod_new_key");

C#

client.SetApiKey("pagr_prod_new_key");

Ruby

client.set_api_key("pagr_prod_new_key")   # returns self

C++

client.set_api_key("pagr_prod_new_key");

Swapping the key can swap the environment

The key prefix decides test vs. production. Replacing a pagr_test_ key with a pagr_prod_ key on a live client silently switches every subsequent render to real, credit-consuming output. There is no other flag and no confirmation.

set_api_key is not thread-safe against in-flight requests in the sense of ordering: a request already on the wire uses the old key, and there’s no way to know which key a concurrent request used. Rotate during a quiet moment, or drain first.

Client lifetime

Two rules, and they differ by SDK because the underlying transports differ:

SDK	Reuse the client?	Dispose?
Python	Yes — owns an httpx connection pool	async with, or await client.aclose() on shutdown
C#	Yes — critical. Owns a pooled HttpClient	using, or Dispose() on shutdown
Java	Yes	try-with-resources, or close()
C++	Yes	RAII — nothing to call
TypeScript	Yes (cheap either way)	Nothing to dispose — no pooled connection
Ruby	Yes	Nothing to dispose — the block form is scoping sugar only

Don’t create a client per request

In C# especially, new PagrApiClient(...) per call creates a new pooled HttpClient per call — the classic socket-exhaustion mistake. Register it as a singleton. The same reasoning applies to Python’s connection pool.

Concurrency and async style

SDK	Style
Python	Async only. Every method is a coroutine; use await and async with.
TypeScript	Async only, on native fetch.
C#	Async only. Every method has an Async suffix and takes a CancellationToken.
Java	Both. PagrApiClient is synchronous; PagrAsyncApiClient mirrors every call returning CompletableFuture<T>.
Ruby	Synchronous only.
C++	Both. Every method has a sync form and a *_async form returning std::future<T>.

C++ async runs on a worker thread

The underlying HTTP client is synchronous, so *_async runs the blocking call on a worker thread rather than doing true async I/O. this is captured by pointer — keep the client alive until the returned future completes.

Other considerations

• Don’t set base_url unless you mean it. It defaults to the hosted API in every SDK. Pointing at the wrong instance is a confusing failure mode — usually surfacing as PagrDecodeError when a proxy or login page answers instead of Pagr.
• Trailing slashes are trimmed for you, so http://localhost:5110/ and http://localhost:5110 behave identically.
• max_retries is client-wide, with no per-call override. If one code path needs a different policy, build a second client.
• max_retries=0 doesn’t disable anything for writes — writes were never retried in the first place.
• wait_for_job gives up after 5 minutes unless you say otherwise. Omitting the timeout applies a default deadline, not unbounded polling — see the per-SDK table.
• Probe once at start-up, not per call. get_status is a cheap readiness check; calling it before every render just doubles your request count against the read rate limit.

Related articles

• Handle errors and retries — the exception tree and the retry policy in detail.
• Authentication — the bearer key, test vs. production, and keeping it safe.
• SDKs — installation and the per-language feature matrix.
• Service status — the health and version probes.