Errors

Every failure thrown by the SDK is a PoliPageException or a subclass. Catch the subclass for targeted handling; catch the base type to handle every SDK error in one place.

The exception hierarchy

PoliPageException exposes four public properties: Code (a PoliPageErrorCode constant), StatusCode (HTTP status, 0 for network failures), Message, and RequestId (server-assigned id, null when no response was received).

using PoliPage;

try
{
    byte[] pdf = await client.Render.PdfAsync(input);
}
catch (PoliPageAuthException)          { await RefreshCredentialsAsync(); }
catch (PoliPageRateLimitException ex)  { await QueueForLaterAsync(ex.RetryAfter); }
catch (PoliPageNotFoundException)      { /* template / version / document missing */ }
catch (PoliPageValidationException ex) { /* malformed input — bad data */ }
catch (PoliPageException ex)
{
    Console.Error.WriteLine($"code={ex.Code} status={ex.StatusCode} requestId={ex.RequestId}");
    throw;
}

Subclasses

Code	When	Recovery
PoliPageAuthException	HTTP 401 or 403 — API key missing, invalid, or lacking permission.	Rotate the key in the dashboard; verify the prefix matches the environment.
PoliPageNotFoundException	HTTP 404 — project, template, version, or document not found.	Verify the slugs and that the template is published in this environment.
PoliPageGoneException	HTTP 410 — resource permanently removed (e.g. soft-deleted document).	Not retryable. Treat as a hard failure.
PoliPageValidationException	HTTP 400 or 422 — request body failed server-side validation.	Inspect Message for the failing field; fix the input.
PoliPageRateLimitException	HTTP 429 — quota exhausted. Exposes RetryAfter.	Automatically retried up to MaxRetries. Honour RetryAfter.
PoliPagePaymentRequiredException	HTTP 402 — organisation has unpaid invoices.	Update the payment method in the dashboard.
PoliPageNetworkException	DNS / TCP / TLS failure or transport-level timeout. StatusCode = 0.	Automatically retried up to MaxRetries.
PoliPageDownloadException	Presigned URL download from storage failed (commonly URL expiry).	Call Documents.GetAsync(id) to refresh the URL.
PoliPageException	Any other API failure, including per-request timeout (Code == Timeout).	Inspect Code and StatusCode to decide.

The wire-level error code is also surfaced verbatim through PoliPageException.Code. Compare against the PoliPageErrorCode constants instead of raw strings:

catch (PoliPageException ex) when (ex.Code == PoliPageErrorCode.QuotaExceeded)
{
    // bespoke handling on top of the SDK's built-in retries.
}

The full code list lives in the reference.

Example

using PoliPage;

var client = new PoliPageClient(new PoliPageClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("POLI_PAGE_API_KEY")!,
});

try
{
    byte[] pdf = await client.Render.PdfAsync(new ProjectModeInput
    {
        Project  = "billing",
        Template = "invoice",
        Version  = "1.0.0",
        Data     = new Dictionary<string, object>
        {
            { "invoiceNumber", "INV-001" },
            { "total", 1280 },
        },
    });
}
catch (PoliPageException ex)
{
    Console.Error.WriteLine($"render failed: code={ex.Code} requestId={ex.RequestId}");
    throw;
}

See also

• Retries and idempotency
• Observability