# Tâches et erreurs

Consultez une tâche, téléchargez son classeur et identifiez les causes d’échec des requêtes.

Documentation officielle: https://img2excel.net/fr/docs/api/jobs

`GET /api/v1/jobs/{job_id}`

Les interfaces synchrones renvoient directement les résultats terminés. Utilisez cette interface pour suivre une tâche asynchrone ou une tentative idempotente en cours, ou renouveler une URL de téléchargement tant que le résultat est conservé. Un échec synchrone renvoie `422` et une réponse de tâche ; consulter une tâche existante renvoie toujours `200`. Vérifiez donc `status`.

Consultez l’état actuel d’une tâche de conversion. Les conversions d’images imprimées et manuscrites utilisent cette même interface.

## Requête

| Paramètre | Emplacement | Obligatoire | Description |
| --- | --- | --- | --- |
| `job_id` | Chemin | Oui | L’`id` renvoyé lors de la création de la tâche. |
| `Authorization` | En-tête | Oui | `Bearer $IMG2EXCEL_API_KEY`. La clé doit appartenir au compte qui a créé la tâche. |

```bash
curl --fail-with-body https://img2excel.net/api/v1/jobs/job_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY"
```

Une requête valide renvoie **200 OK**, même si la conversion a échoué. Vérifiez toujours `status` dans le JSON : une requête HTTP réussie ne signifie pas que le classeur est prêt.

## États des tâches

| État | Signification | Étape suivante |
| --- | --- | --- |
| `queued` | Envoi accepté, tâche en attente. | Consulter à nouveau après 2 à 3 secondes. |
| `processing` | Conversion en cours. | Consulter à nouveau après 2 à 3 secondes. |
| `succeeded` | Classeur prêt. | Télécharger le fichier via `result.download_url` et arrêter le suivi. |
| `failed` | Échec de conversion. | Lire `error.code` et `error.message`, puis arrêter le suivi. |
| `expired` | Durée de conservation écoulée. | Arrêter le suivi. Si nécessaire, créer une tâche avec une nouvelle clé d’idempotence. |

## Réponse

### Conversion réussie

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-09-07T12:00:00.000Z",
  "completed_at": "2026-09-07T12:00:18.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}

```

L’URL ci-dessus est un exemple. Utilisez celle renvoyée pour votre propre tâche.

| Champ | Type | Description |
| --- | --- | --- |
| `id` | Chaîne | Identifiant de tâche. |
| `type` | Chaîne | `image-to-excel` ou `handwriting-to-excel`. |
| `status` | Chaîne | L’un des cinq états ci-dessus. |
| `credits_reserved` | Entier | Crédits nécessaires à la conversion. |
| `credits_used` | Entier | Crédits consommés par la conversion. |
| `created_at` | Chaîne | Horodatage UTC au format ISO 8601. |
| `completed_at` | Chaîne ou null | Heure de fin ; `null` avant la fin. |
| `result` | Objet | Présent si la conversion a réussi et le résultat est disponible. |
| `error` | Objet | Présent en cas d’échec ; contient `code` et `message`. |

### Champs du résultat

| Champ | Type | Description |
| --- | --- | --- |
| `filename` | Chaîne | Nom de fichier suggéré pour le classeur. |
| `content_type` | Chaîne | Type MIME XLSX. |
| `size_bytes` | Entier ou null | Taille du fichier en octets ; `null` si indisponible. |
| `download_url` | Chaîne | URL de téléchargement signée temporaire. |
| `download_url_expires_in` | Entier | Validité de l’URL en secondes : `900` (15 minutes). |

Le résultat reste disponible pendant 24 heures après la conversion. Si l’URL expire pendant cette période, consultez à nouveau la tâche pour la renouveler. Ne consignez pas les URL signées dans les journaux et ne les publiez pas.

### Conversion échouée

L’échec de conversion est indiqué dans la réponse de tâche, par exemple :

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "failed",
  "credits_reserved": 1,
  "credits_used": 0,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:18.000Z",
  "error": {
    "code": "CONVERSION_FAILED",
    "message": "The conversion could not be completed."
  }
}
```

Une conversion échouée ne consomme pas de crédits. Vérifiez le message avant de réessayer : une nouvelle conversion nécessite une nouvelle clé d’idempotence. L’ancienne clé renvoie la même tâche échouée.

## Suivi et téléchargement

Installez `requests` avec `pip install requests`, définissez `IMG2EXCEL_API_KEY` et remplacez `job_id` par votre ID de tâche. Cet exemple effectue au maximum 60 consultations. Une erreur réseau ou HTTP arrête le script ; en production, gérez les erreurs temporaires selon les recommandations ci-dessous.

```python
import os
import time
import requests

job_id = "job_0123456789abcdef0123456789abcdef"
headers = {"Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}"}

for _ in range(60):
    response = requests.get(
        f"https://img2excel.net/api/v1/jobs/{job_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()

    if job["status"] == "succeeded":
        xlsx = requests.get(job["result"]["download_url"], timeout=60)
        xlsx.raise_for_status()
        with open(job["result"]["filename"], "wb") as output:
            output.write(xlsx.content)
        break
    if job["status"] in ("failed", "expired"):
        raise RuntimeError(job.get("error", {"code": job["status"]}))

    time.sleep(2)
else:
    raise TimeoutError("IMG2Excel conversion did not finish in time")

```

## Erreurs de requête

Une requête HTTP refusée renvoie un statut autre que 2xx et un objet d’erreur :

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "A valid API key is required."
  }
}
```

| Statut HTTP | Code | Cause | Solution |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | Corps illisible en tant que formulaire multipart. | Utiliser l’envoi de fichiers multipart du client HTTP. |
| 400 | `INVALID_FILE` | Champ `file` absent ou ne contenant pas de fichier. | Joindre une image dans le champ `file`. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Clé de plus de 200 caractères. | Raccourcir la valeur de l’en-tête. |
| 401 | `INVALID_API_KEY` | Clé absente, invalide, expirée, révoquée ou sans les autorisations de conversion nécessaires. | Vérifier l’en-tête Bearer et la clé dans les [paramètres API](https://img2excel.net/fr/settings/api). |
| 403 | `API_ACCESS_REQUIRED` | Le compte n’a pas accès à l’API. | Acheter le pack Business ou Professionnel. |
| 404 | `JOB_NOT_FOUND` | Tâche inexistante ou appartenant à un autre compte. | Vérifier l’ID et utiliser une clé du compte ayant créé la tâche. |
| 409 | `JOB_CONFLICT` | Un conflit empêche la création. | Réessayer avec la clé d’idempotence initiale pour récupérer la tâche existante. |
| 413 | `FILE_TOO_LARGE` | Fichier supérieur à 4 Mo. | Réduire sa taille avant l’envoi. |
| 429 | `RATE_LIMITED` | Trop de tâches créées durant la dernière minute. | Attendre selon `Retry-After`, puis réessayer avec la même clé. |
| 429 | `CONCURRENCY_LIMITED` | Trop de tâches en attente ou en cours sur le compte. | Attendre la fin d’une tâche avant d’en envoyer une autre. |

Un manque de crédits ou un échec de reconnaissance peut survenir **après** l’acceptation d’une tâche. La consultation renvoie alors `status: "failed"`, `error.code` et `error.message`, sans que l’envoi initial ait nécessairement été refusé. Vérifiez le solde si le message indique un manque de crédits.

## Limites et nouvelles tentatives

| Limite | Valeur |
| --- | --- |
| Nouvelles tâches par compte | 30 par minute, pour les deux interfaces de conversion réunies |
| Tâches simultanées en attente ou en cours | Business : 3 ; Professionnel : 10 |
| Taille du fichier | 4 Mo maximum |
| Validité de l’URL de téléchargement | 15 minutes |
| Conservation du résultat | 24 heures après une conversion réussie |

Pour `429`, respectez `Retry-After` si présent. Pour les erreurs temporaires `5xx` ou réseau, augmentez progressivement le délai entre les tentatives avec un délai aléatoire supplémentaire. Réutilisez la clé initiale pour un envoi et le même ID pour une consultation. Fixez une durée maximale de suivi dans votre application.

Ne retentez pas automatiquement les requêtes invalides ou les erreurs d’authentification. Corrigez d’abord la requête. Si le problème persiste, contactez le [support](mailto:support@img2excel.net) avec l’ID de tâche et le code d’erreur, sans clé API ni URL de téléchargement.

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Documentation API complète: https://img2excel.net/fr/docs/api/text/llms-full.txt