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

# Gestion des erreurs

> Hiérarchie des exceptions du SDK Java GIMpay et bonnes pratiques d'intégration.

Le SDK lève des exceptions spécifiques pour vous permettre de réagir différemment selon le type d'erreur.

## Hiérarchie des exceptions

```
SdkException (base)
├── TechnicalException (réseau, timeout, sérialisation...)
└── ApiException (réponse d'erreur de l'API GIMpay)
    ├── BadRequestException (400)
    ├── AuthenticationException (401)
    ├── UnauthorizedException (403)
    ├── NotFoundException (404)
    └── ServerErrorException (5xx)
```

## Exemple de gestion complète

```java theme={null}
import com.gimpaysdk.exception.*;

try {
    Double balance = sdk.wallets().getBalance("REF_WALLET_INEXISTANT");
    System.out.println("Solde : " + balance);
} catch (NotFoundException e) {
    log.warn("La ressource (portefeuille) n'a pas été trouvée.", e);
} catch (AuthenticationException e) {
    log.error("Erreur d'authentification. Vérifiez vos identifiants.", e);
} catch (UnauthorizedException e) {
    log.error("Droits insuffisants pour effectuer cette action.", e);
} catch (ApiException e) {
    log.error("Erreur API non gérée : Status={}, Body={}", e.getStatusCode(), e.getResponseBody(), e);
} catch (TechnicalException e) {
    log.error("Erreur technique (réseau, etc.) : {}", e.getMessage(), e);
}
```

## Bonnes pratiques

### Instance unique du SDK (singleton)

Le SDK est **thread-safe**. Pour des performances optimales, ne l'initialisez qu'une seule fois au démarrage de votre application.

```java theme={null}
// Exemple dans une application Spring
@Configuration
public class GIMpayConfig {
    @Bean
    public GIMpaySdk gimpaySdk(
        @Value("${gimpay.client-id}") String clientId,
        @Value("${gimpay.client-secret}") String clientSecret,
        @Value("${gimpay.base-url}") String baseUrl
    ) {
        return GIMpaySdk.init(clientId, clientSecret, baseUrl);
    }
}
```

### Logging

Le SDK utilise **SLF4J**. Pour activer les logs, ajoutez une implémentation à votre projet :

```xml pom.xml theme={null}
<!-- Pour afficher les logs dans la console -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.12</version>
    <scope>runtime</scope>
</dependency>
```

Configurez ensuite le niveau de log pour le package `com.gimpaysdk` sur `DEBUG`.

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Dépannage" icon="wrench" href="/sdks/java/troubleshooting">
    Solutions aux problèmes les plus courants.
  </Card>

  <Card title="Démarrage rapide" icon="rocket" href="/sdks/java/quickstart">
    Revoir l'initialisation et les exemples d'utilisation.
  </Card>
</CardGroup>