# Dépannage

## Core inaccessible

- **Symptôme :** `RelaiException` sans status HTTP.
- **Cause :** Core arrêté, DNS/port/réseau Docker.
- **Solution :** tester l'URL depuis le même processus/conteneur PHP.

## Mauvais `baseUrl`

- **Symptôme :** validation locale ou 404.
- **Cause :** URL relative ou `/api/v1` ajouté deux fois.
- **Solution :** utiliser `http://localhost:3000` sans préfixe API.

## Token invalide

- **Symptôme :** `RelaiApiException` 401.
- **Cause :** token expiré, révoqué, incorrect ou app inactive.
- **Solution :** vérifier le secret injecté et créer un nouveau token.

## Scope manquant

- **Symptôme :** 403 mentionnant un scope.
- **Cause :** token au périmètre insuffisant.
- **Solution :** ajouter uniquement le scope requis; chat avec tools en demande deux.

## App inactive ou mauvais slug

- **Symptôme :** 401/403 ou validation locale du slug.
- **Cause :** app désactivée, `appSlug` absent/différent du token.
- **Solution :** corriger l'app et `RELAI_APP_SLUG`.

## Provider/Ollama indisponible

- **Symptôme :** 5xx, timeout, run failed.
- **Cause :** provider désactivé, URL inaccessible depuis Core, modèle absent.
- **Solution :** diagnostiquer depuis le Core et inspecter le run; le SDK ne contacte
  pas Ollama.

## Tool introuvable ou inactif

- **Symptôme :** 404/403.
- **Cause :** nom incorrect, tool inactif/non autorisé/non read-only, hors allowlist
  chat ou scope `tools:execute` absent.
- **Solution :** vérifier déclaration, application autorisée, allowlist transmise à
  `chat()->send()` et politique Core V1.

## Structured avec tools

- **Symptôme :** `RelaiValidationException` sur `tools`.
- **Cause :** `/api/v1/structured` ne supporte pas les tool loops en V1.
- **Solution :** utiliser `chat()->send()` pour le tool calling.

## Timeout

- **Symptôme :** `RelaiTimeoutException`.
- **Cause :** délai trop court ou dépendance lente.
- **Solution :** inspecter run/tool, puis ajuster `timeoutSeconds` si nécessaire.

## Réponse non JSON

- **Symptôme :** `RelaiValidationException` sur la réponse.
- **Cause :** proxy HTML ou mauvaise URL.
- **Solution :** inspecter proxy et endpoint; les succès couverts doivent être JSON.

## Structured output invalide

- **Symptôme :** 502 et run failed.
- **Cause :** sortie provider non conforme au JSON Schema.
- **Solution :** simplifier/contraindre le schéma, choisir un modèle adapté et inspecter
  le run côté Core.