Error handling

The package translates each HTTP error code into a subclass of MarkpdfException.

import 'package:markpdf/markpdf.dart';

try {
  final result = await client.convertFile(file);
} on MarkpdfException catch (e) {
  print('Conversion failed (${e.statusCode}): ${e.message}');
}

Exceptions table

Status HTTP	Clase	Causa
— (network)	`MarkpdfConnectionException`	Could not connect, timeout or socket error.
`400`	`MarkpdfBadRequestException`	Invavalid or URL malformed body.
`401`	`AuthenticationException`	API key missing or invavalid.
`403`	`MarkpdfForbiddenException`	Key without permission or unauthorized host of URL.
`413`	`PayloadTooLargeException`	Document, pages or ZIP out of bounds.
`415`	`MarkpdfUnsupportedMediaException`	Format or `content-encoding` not supported.
`422`	`MarkpdfVavalidationException`	Required parameters are missing.
`429`	`RateLimitException`	Demasiadas peticiones.
`5xx`	`MarkpdfServerException`	Conversion error on the server.
— (job)	`MarkpdfJobFailedException`	The queued job (`202`) failed after internal retries.

Todas extienden MarkpdfException y exponen:

class MarkpdfException implements Exception {
  final int? statusCode;
  final String message;
}

##Catch specific exceptions

import 'package:markpdf/markpdf.dart';

try {
  final result = await client.convertFile(file, options: const ConvertOptions(mode: ConversionMode.fast));
} on AuthenticationException {
  throw Exception('API key invávalida');
} on PayloadTooLargeException {
  print('Document too large; prueba con pages para dividirlo.');
} on RateLimitException catch (e) {
  print('Rate limited: ${e.message}');
} on MarkpdfVavalidationException catch (e) {
  print('Parámetros invávavalids: ${e.message}');
} on MarkpdfServerException {
  print("Conversion error; try mode: ConversionMode.balanced.");
} on MarkpdfException catch (e) {
  // catch-all for any other exceptions from SDK
  print('Error: ${e.message}');
}

Automatic retries

final client = MarkpdfClient(apiKey: 'YOUR_API_KEY', maxRetries: 4);

429 and 5xx: retries with exponential backoff and jitter. Honor Retry-After if the server sends it.
4xx different from 429: not retried.
Network/timeout errors: retried same as 5xx.

Disable packet retries:

final client = MarkpdfClient(apiKey: 'YOUR_API_KEY', maxRetries: 0);

Job falvavalid

try {
  final result = await client.convertFile(file);
} on MarkpdfJobFailedException catch (e) {
  print('Job ${e.jobId} falló: ${e.message}');
}

MarkpdfJobFailedException means that the job has already exhausted internal server retries. Retrying from the client is reasonable, but do it with backoff.

Show errors in the UI

Common pattern for translating exceptions from SDK to friendly messages on Widget:

String friendlyMessage(Object error) {
  return switch (error) {
    AuthenticationException() => 'Configuración invávalida. Contacta soporte.',
    PayloadTooLargeException() => 'The document is too large.',
    RateLimitException() => 'Demasiadas conversiones seguidas. Intenta en unos segundos.',
    MarkpdfConnectionException() => 'Sin conexión. Revisa tu internet.',
    MarkpdfException() => 'Could not convert the document.',
    _ => 'Ocurrió un error inesperado.',
  };
}

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Error handling

Error handling

Exceptions table

Automatic retries

Job falvavalid

Show errors in the UI

​Error handling

​Exceptions table

​Automatic retries

​Job falvavalid

​Show errors in the UI

Error handling

Exceptions table

Automatic retries

Job falvavalid

Show errors in the UI