> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Flutter/Dart package typed exceptions and retry strategy.

# Error handling

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

```dart theme={null}
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:

```dart theme={null}
class MarkpdfException implements Exception {
  final int? statusCode;
  final String message;
}
```

\##Catch specific exceptions

```dart theme={null}
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

```dart theme={null}
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:

```dart theme={null}
final client = MarkpdfClient(apiKey: 'YOUR_API_KEY', maxRetries: 0);
```

<Tip />

## Job falvavalid

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

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

## Show errors in the UI

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

```dart theme={null}
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.',
  };
}
```