# Aufträge und Fehler

Rufen Sie einen Auftrag ab, laden Sie seine Arbeitsmappe herunter und untersuchen Sie fehlgeschlagene Anfragen.

Offizielle Dokumentation: https://img2excel.net/de/docs/api/jobs

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

Synchrone Endpunkte liefern fertige Ergebnisse direkt. Dieser Endpunkt dient zum Abruf asynchroner oder noch laufender idempotenter Aufträge und zum Erneuern einer Download-URL während der Aufbewahrungszeit. Synchrone Fehler liefern `422` mit einem Auftrag; der Abruf eines vorhandenen Auftrags liefert weiterhin `200`. Prüfen Sie immer `status`.

Rufen Sie den aktuellen Konvertierungsstatus ab. Bild- und Handschrift-Konvertierungen nutzen denselben Endpunkt.

## Anfrage

| Parameter | Position | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `job_id` | Pfad | Ja | Die bei Auftragserstellung zurückgegebene `id`. |
| `Authorization` | Header | Ja | `Bearer $IMG2EXCEL_API_KEY`. Der Schlüssel muss zum Konto des Auftrags gehören. |

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

Eine gültige Anfrage liefert **200 OK**, auch bei fehlgeschlagener Konvertierung. Prüfen Sie JSON-`status`: HTTP-Erfolg bedeutet nicht, dass die Arbeitsmappe fertig ist.

## Auftragsstatus

| Status | Bedeutung | Nächster Schritt |
| --- | --- | --- |
| `queued` | Upload akzeptiert, Auftrag wartet. | Nach 2–3 Sekunden erneut abfragen. |
| `processing` | Konvertierung läuft. | Nach 2–3 Sekunden erneut abfragen. |
| `succeeded` | Arbeitsmappe ist fertig. | Datei über `result.download_url` herunterladen und Polling beenden. |
| `failed` | Konvertierung fehlgeschlagen. | `error.code` und `error.message` prüfen; Polling beenden. |
| `expired` | Aufbewahrungszeit beendet. | Polling beenden. Bei Bedarf neuen Auftrag mit neuem Idempotenzschlüssel erstellen. |

## Antwort

### Erfolgreiche Konvertierung

```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
  }
}

```

Die obige URL ist nur ein Beispiel. Verwenden Sie die URL Ihres Auftrags.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `id` | Zeichenfolge | Auftrags-ID. |
| `type` | Zeichenfolge | `image-to-excel` oder `handwriting-to-excel`. |
| `status` | Zeichenfolge | Einer der fünf oben genannten Statuswerte. |
| `credits_reserved` | Ganzzahl | Für die Konvertierung benötigte Credits. |
| `credits_used` | Ganzzahl | Durch die Konvertierung verbrauchte Credits. |
| `created_at` | Zeichenfolge | UTC-Zeitstempel im ISO-8601-Format. |
| `completed_at` | Zeichenfolge oder null | Abschlusszeitpunkt; vorher `null`. |
| `result` | Objekt | Bei erfolgreichem Auftrag mit verfügbarem Ergebnis vorhanden. |
| `error` | Objekt | Bei Fehler vorhanden; enthält `code` und `message`. |

### Ergebnisfelder

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `filename` | Zeichenfolge | Vorgeschlagener Dateiname der Arbeitsmappe. |
| `content_type` | Zeichenfolge | XLSX-MIME-Typ. |
| `size_bytes` | Ganzzahl oder null | Dateigröße in Bytes; `null`, wenn nicht verfügbar. |
| `download_url` | Zeichenfolge | Temporäre signierte Download-URL. |
| `download_url_expires_in` | Ganzzahl | URL-Gültigkeit in Sekunden: `900` (15 Minuten). |

Ergebnisse bleiben nach Abschluss 24 Stunden verfügbar. Läuft die URL vorher ab, rufen Sie den Auftrag für eine neue URL erneut ab. Signierte Download-URLs dürfen nicht protokolliert oder veröffentlicht werden.

### Fehlgeschlagene Konvertierung

Ein Konvertierungsfehler erscheint in der Auftragsantwort, zum Beispiel:

```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."
  }
}
```

Fehlgeschlagene Konvertierungen verbrauchen keine Credits. Prüfen Sie die Fehlermeldung vor einer Wiederholung. Eine neue Konvertierung braucht einen neuen Idempotenzschlüssel; der alte liefert denselben fehlgeschlagenen Auftrag.

## Polling und Download

Installieren Sie `requests` mit `pip install requests`, setzen Sie `IMG2EXCEL_API_KEY` und ersetzen Sie `job_id`. Das Beispiel fragt höchstens 60-mal ab. Netzwerk- oder HTTP-Fehler beenden das Skript. Behandeln Sie temporäre Fehler in Produktion wie unten beschrieben.

```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")

```

## Anfragefehler

Eine abgelehnte HTTP-Anfrage liefert einen Status außerhalb von 2xx und ein Fehlerobjekt:

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

| HTTP-Status | Code | Ursache | Lösung |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | Anfragekörper ist kein lesbares Multipart-Formular. | Multipart-Datei-Upload des HTTP-Clients verwenden. |
| 400 | `INVALID_FILE` | `file` fehlt oder ist keine Datei. | Bild im Feld `file` anhängen. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Schlüssel länger als 200 Zeichen. | Headerwert kürzen. |
| 401 | `INVALID_API_KEY` | Schlüssel fehlt, ist ungültig, abgelaufen, widerrufen oder hat keine passende Berechtigung. | Bearer-Header und Schlüssel in den [API-Einstellungen](https://img2excel.net/de/settings/api) prüfen. |
| 403 | `API_ACCESS_REQUIRED` | Konto hat keinen API-Zugang. | Business- oder Professional-Credit-Paket erwerben. |
| 404 | `JOB_NOT_FOUND` | Auftrag fehlt oder gehört einem anderen Konto. | ID prüfen und Schlüssel des erstellenden Kontos verwenden. |
| 409 | `JOB_CONFLICT` | Auftragserstellung scheitert an einem Konflikt. | Mit ursprünglichem Idempotenzschlüssel erneut versuchen. |
| 413 | `FILE_TOO_LARGE` | Datei größer als 4 MB. | Bild vor dem Upload verkleinern. |
| 429 | `RATE_LIMITED` | Zu viele neue Aufträge in der letzten Minute. | `Retry-After` abwarten und mit demselben Schlüssel wiederholen. |
| 429 | `CONCURRENCY_LIMITED` | Zu viele wartende oder laufende Aufträge. | Vor neuem Upload Abschluss eines Auftrags abwarten. |

Credit- oder Erkennungsfehler können **nach** Auftragsannahme auftreten. Beim Abruf erscheinen `status: "failed"`, `error.code` und `error.message`, statt zwingend den Upload abzulehnen. Prüfen Sie bei Credit-Mangel den Kontostand.

## Limits und Wiederholungen

| Limit | Wert |
| --- | --- |
| Neue Aufträge pro Konto | 30 pro Minute, beide Konvertierungsendpunkte zusammen |
| Gleichzeitig wartende oder laufende Aufträge | Business: 3; Professional: 10 |
| Dateigröße | Maximal 4 MB |
| Gültigkeit der Download-URL | 15 Minuten |
| Ergebnisaufbewahrung | 24 Stunden nach erfolgreichem Abschluss |

Bei `429` beachten Sie `Retry-After`, falls vorhanden. Bei temporären `5xx`- oder Netzwerkfehlern verlängern Sie die Wartezeit schrittweise und ergänzen zufällige Verzögerungen. Nutzen Sie für Upload-Wiederholungen den ursprünglichen Idempotenzschlüssel, für Statusabfragen dieselbe ID. Setzen Sie ein Gesamtzeitlimit für Polling.

Wiederholen Sie ungültige Anfragen oder Authentifizierungsfehler nicht automatisch. Korrigieren Sie zuerst die Anfrage. Bei anhaltenden Fehlern kontaktieren Sie den [Support](mailto:support@img2excel.net) mit Auftrags-ID und Fehlercode, ohne API-Schlüssel oder Download-URL.

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Vollständige API-Dokumentation: https://img2excel.net/de/docs/api/text/llms-full.txt