API Failure handling · 8 min read

Errors

BladePDF errors can happen before the request is sent, while the API validates the render, or while the PDF is being generated. Handle them explicitly so your app can retry safely or show useful feedback.

Package exceptions

Exception	Cause
`MissingApiKeyException`	`BLADEPDF_API_KEY` is empty.
`AssetNotFoundException`	A manually attached asset path does not exist.
`AssetAccessDeniedException`	An automatically discovered file resolves outside the configured roots.
`UnableToWritePdfException`	`save()` could not write every PDF byte to the destination.
`InvalidRenderConfigurationException`	The fluent API was used in an unsupported combination, such as header HTML on a cloud template render or `async()` without `storePdf()`.
`RenderFailedException`	BladePDF returned a non-successful HTTP response.

Handling exceptions

Controller

php

 1use BladePDF\Exceptions\BladePdfException;
 2use BladePDF\Exceptions\RenderFailedException;
 3use Illuminate\Support\Facades\Log;
 4
 5try {
 6    return BladePDF::fromTemplate('invoice.standard', $context)
 7        ->reference($invoice->uuid)
 8        ->render()
 9        ->download('invoice.pdf');
10} catch (RenderFailedException $e) {
11    Log::warning('BladePDF render failed', [
12        'invoice_id' => $invoice->id,
13        'status' => $e->statusCode(),
14        'request_id' => $e->requestId(),
15    ]);
16
17    return back()->withErrors([
18        'pdf' => 'The PDF could not be generated. Please try again.',
19    ]);
20} catch (BladePdfException $e) {
21    report($e);
22
23    return back()->withErrors(['pdf' => 'The PDF request is invalid.']);
24}

RenderFailedException::responseBody() provides the full response for controlled diagnostics. Its exception message contains only a bounded excerpt, and requestId() exposes the API correlation ID.

Node.js errors

Node.js error classes use the conventional Error suffix: BladePdfError, MissingApiKeyError, InvalidRenderConfigurationError, AssetNotFoundError, AssetAccessDeniedError, UnableToWritePdfError, and RenderFailedError.

Node.js

typescript

 1try {
 2  await render.render();
 3} catch (error) {
 4  if (error instanceof RenderFailedError) {
 5    console.error(error.statusCode, error.requestId);
 6  }
 7}

RenderFailedError exposes readonly statusCode, requestId, responseBody, and cause. Caller cancellation remains a standard AbortError.

API status codes

Status	Meaning	Typical fix
`400`	Invalid render request.	Check source, context, metadata, options, and required files.
`401`	Missing authentication.	Set `BLADEPDF_API_KEY`.
`403`	The API key is not allowed to render.	Check API key, account, and plan status.
`408`	Render timed out.	Reduce complexity or increase plan/render timeout if available.
`413`	Payload is too large.	Reduce HTML/context/assets size.
`429`	Concurrency or queue limit reached.	Retry later with backoff or lower concurrency.
`500`	Unexpected render failure.	Check dashboard logs and retry if safe.
`508`	Daily bandwidth limit reached.	Wait for reset or adjust plan.
`509`	Monthly bandwidth limit reached.	Wait for reset or adjust plan.

Common validation errors

Missing main html input file. The request was source: html but no HTML file was sent.
Missing context input file. The request was source: template but no context JSON file was sent.
HTML file fields are not supported for template render source. Cloud template renders cannot include html, header_html, or footer_html.
metadata.template_name is only supported for html render source. Use reference() for cloud templates.
waitUntil option requires waitFunction Use waitFunction() when waitUntil('function') is set.
Asynchronous renders require store_pdf=true. Call storePdf() before async().
Asynchronous renders require available PDF storage... Free workspace storage before submitting another async render.

Render limit errors

BladePDF enforces limits for render time, PDF size, payload size, network access, and asset requests. Limit errors appear in dashboard logs and are delivered through pdf.failed webhooks.

Safe retries

Retrying is usually safe when your render operation has no side effects. Use your own idempotency key or reference() value to avoid duplicate downstream work.

Retry reference

php

 1BladePDF::fromTemplate('invoice.standard', $context)
 2    ->reference($invoice->uuid)
 3    ->render()
 4    ->pdf();

Debugging

Every render appears in the dashboard with request id, logs, timing metrics, asset counts, failure message, and template/reference metadata. Start there when a render fails in production.