# Batch-Aufträge Mehrere API-Anfragen asynchron mit einem einzigen Datei-Upload verarbeiten. Die Batch Jobs-API ermöglicht die Durchführung von Massenoperationen auf Stripe-Ressourcen. Anstatt für jede einzelne Operation eine separate API-Anfrage zu senden, die Begrenzungen auslösen könnte, können Sie eine Datei mit allen Vorgängen hochladen und Stripe diese asynchron verarbeiten lassen. Verwenden Sie dies für einmalige Migrationen, Massenaktualisierungen oder jede Operation, die die Verarbeitung vieler Ressourcen erfordert. ## Wann Sie Batch-Aufträge verwenden sollten Batch-Aufträge funktionieren gut für: - **Massenmigrationen**: Verschieben großer Mengen von Abonnements in neue Abrechnungsmodi. - **Massenaktualisierungen**: Gleichzeitige Aktualisierung mehrerer Konten oder Abonnements. Batch-Aufträge eignen sich nicht für: - Vorgänge, die eine sofortige synchrone Antwort erfordern. - Echtzeitverarbeitung mit engen zeitlichen Anforderungen. - Ein einzelner asynchroner Aufruf. Führen Sie zum die folgenden Schritte aus, um einen Batch-Auftrag zu verarbeiten: 1. [Erstellen Sie einen Batch-Auftrag](https://docs.stripe.com/batch-api.md#create-a-batch-job) und geben Sie den Ziel-API-Endpoint an. 1. [Laden Sie die Eingabedatei](https://docs.stripe.com/batch-api.md#upload-the-input-file) mit Ihren Batch-Anfragen hoch. 1. [Überwachen Sie den Auftragsstatus](https://docs.stripe.com/batch-api.md#monitor-job-status) über Webhooks oder Abfragen. 1. [Laden Sie die Ergebnisse herunter](https://docs.stripe.com/batch-api.md#download-the-results). ## Unterstützte Endpoints Die Batch Jobs-API unterstützt die folgenden Endpoints. Jeder Batch-Auftrag zielt auf einen einzelnen Endpoint ab und alle Anfragen im Stapel werden an diesen Endpoint gesendet. | Endpoint | Pfad | | ------------------------------------------------------------------------------------------ | ------------------------------------ | | [Aktualisieren einer Kundin/eines Kunden](https://docs.stripe.com/api/customers/update.md) | POST `/v1/customers/:id` | | [Erstellen eines Aktionscodes](https://docs.stripe.com/api/promotion_codes/create.md) | POST `/v1/promotion_codes` | | [Aktualisieren eines Aktionscodes](https://docs.stripe.com/api/promotion_codes/update.md) | POST `/v1/promotion_codes/:id` | | [Migrieren eines Abonnements](https://docs.stripe.com/api/subscriptions/migrate.md) | POST `/v1/subscriptions/:id/migrate` | | [Ein Abo aktualisieren](https://docs.stripe.com/api/subscriptions/update.md) | POST `/v1/subscriptions/:id` | ## Einschränkungen Prüfen Sie die folgenden Einschränkungen: - Batch-Dateien sind auf 5 GB begrenzt. Wenn Sie eine größere Datei für ein höheres Volumen an Anfragen verarbeiten müssen, teilen Sie sie in mehrere Batches auf. - Batch-Aufträge unterstützen nur JSONL-Dateien (newline-delimited JSON). Batch-Aufträge akzeptieren keine CSV- oder andere Formate. - Batch-Anfragen können nur `POST` oder `DELETE` verwenden. Batch-Aufträge unterstützen `GET` nicht. - Alle Anfragen in einem Batch müssen auf denselben API-Endpoint abzielen. - Batch-Aufträge garantieren keine bestimmte Reihenfolge der Anfrageverarbeitung. - Batch-Aufträge haben eine maximale Bearbeitungsdauer von 24 Stunden. Aufträge, die diesen Grenzwert überschreiten, gehen in den Status `timeout` über, wobei Teilergebnisse verfügbar sind. - Die Ergebnisse können 7 Tage nach Abschluss des Auftrags heruntergeladen werden. - Die Upload-URL läuft 5 Minuten nach der Erstellung des Auftrags ab. Nach Ablauf dieser Frist wechselt der Auftrag in den Status `upload_timeout` und Sie müssen einen neuen Auftrag erstellen. - Laden Sie die Datei mit einer direkten HTTP-`PUT`-Anfrage an die vorsignierte URL hoch. ## Einen Batch-Auftrag erstellen Erstellen Sie zunächst einen Batch-Auftrag, indem Sie eine `POST`-Anfrage an `/v2/core/batch_jobs` senden. Geben Sie den Ziel-Endpoint und alle Verarbeitungsoptionen an: ```bash curl https://api.stripe.com/v2/core/batch_jobs \ -u <>: \ -H "Content-Type: application/json" \ -H "Stripe-Version: 2026-03-25.preview" \ -d '{ "endpoint": { "path": "/v1/subscriptions/:id/migrate", "http_method": "post" }, "maximum_rps": 10, "skip_validation": false }' ``` Der Inhaltstyp für diese Anfrage ist eine JSON-Datei. Dadurch wird ein Batch-Auftrags-Objekt mit dem Status `ready_for_upload` zurückgegeben. Die Upload-URL und ihre Ablaufzeit befinden sich im Feld `status_details`: ```json { "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz", "object": "v2.core.batch_job", "created": "2026-03-09T20:55:31.000Z", "maximum_rps": 10, "skip_validation": false, "status": "ready_for_upload", "status_details": { "ready_for_upload": { "upload_url": { "expires_at": "2026-03-09T21:00:31.000Z", "url": "https://stripeusercontent.com/files/upload/..." } } } } ``` Das Objekt `status_details` ändert sich je nach aktuellem Status. Wenn der Auftrag `ready_for_upload` lautet, enthält er die vorsignierte Upload-URL und den Ablaufzeitstempel. ### Parameter | Parameter | Erforderlich | Beschreibung | | -------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `endpoint.path` | Ja | Der zu verwendende API-Endpoint (z. B. `/v1/subscriptions/:id/migrate`). Siehe [Unterstützte Endpoints](https://docs.stripe.com/batch-api.md#supported-endpoints). | | `endpoint.http_method` | Ja | HTTP-Methode für den Endpoint. Derzeit wird nur `post` unterstützt. | | `maximum_rps` | Nein | Maximal verarbeitete Anfragen pro Sekunde (1–100). Standardmäßig 10. | | `skip_validation` | Nein | Wählen Sie `true`, um die Validierung der Eingabedatei zu überspringen und sofort mit der Verarbeitung zu beginnen. Der Standardwert lautet `false`. | | `notification_suppression` | Nein | Steuert, ob Webhooks aus den zugrunde liegenden API-Vorgängen zugestellt werden. Wähhlen Sie `{"scope": "all"}` aus, um Webhooks auf Operationsebene zu unterdrücken. Batch-Ereignisse werden unabhängig von dieser Einstellung immer zugestellt. Der Standardwert lautet `{"scope": "none"}`. | | `metadata` | Nein | Schlüssel-Wert-Paare für Ihre interne Nachverfolgung. Metadaten sind in Batch-Auftrags-Ereignissen enthalten, einschließlich Fehlerereignissen. | ## Eingabedatei hochladen Nachdem Sie den Batch-Auftrag erstellt haben, laden Sie Ihre Eingabedatei in die URL in `status_details.ready_for_upload.upload_url.url` hoch. Verwenden Sie eine `PUT`-Anfrage mit dem Dateiinhalt: ```bash curl {UPLOAD_URL} \ -X PUT \ -T input.jsonl \ -H "Content-Type: application/jsonlines" ``` Die Eingabedatei für diese Anfrage muss eine JSONL-Datei sein, und der Inhaltstyp muss `application/octet-stream` sein. Nach Abschluss des Uploads beginnt Stripe automatisch mit der Verarbeitung. Es gibt keinen separaten Schritt `start`. Die Upload-URL läuft 5 Minuten nach Erstellung des Batch-Auftrags ab. Im Feld `expires_at` können Sie die genaue Frist sehen. Wenn die URL abläuft, bevor Sie die Datei hochladen, ändert sich der Status des Auftrags in `upload_timeout`, und Sie müssen einen neuen Batch-Auftrag erstellen. Generieren Sie die Eingabedatei, bevor Sie den Batch-Auftrag erstellen, damit Sie sie umgehend hochladen können. ### Eingabedateiformat Die Datei muss UTF-8-codiert sein und das JSONL-Format verwenden (newline-delimited JSON-Zeile, also ein Objekt pro Zeile). Jede Zeile stellt eine einzelne API-Anfrage an den Ziel-Endpoint dar. CSV und andere Formate werden nicht unterstützt. Jedes JSON-Objekt unterstützt die folgenden Felder: | Feld | Erforderlich | Beschreibung | | ------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Ja | Eine eindeutige Kennung, um diese Anfrage mit ihrem Ergebnis zu verknüpfen. Die IDs der Pfadparameter und die IDs auf dem Endpoint müssen übereinstimmen, wobei der Nutzer/die Nutzerin frei wählen kann, wie er/sie sie benennen möchte: muss übereinstimmen mit `/^[A-Za-z0-9_-]+$/`. | | `path_params` | Vorbehaltlich | Pfadparameter für den Endpoint. Erforderlich, wenn der Endpoint-Pfad Platzhalter enthält (zum Beispiel `:id`). Die Schlüssel in `path_params` müssen genau mit den Platzhaltern im Endpoint-Pfad übereinstimmen. | | `params` | Nein | Parameter des Anfragetextes für den API-Aufruf. Je nach API-Methode können Abweichungen auftreten. | | `context` | Nein | Die ID eines Stripe-Kontos. Verwenden Sie diese, um die Anfrage für ein bestimmtes Konto, z. B. ein verbundenes Konto, auszuführen. | ### Beispiel für eine Eingabedatei #### API-Methode - POST /v1/customers/:id Für den Endpoint `POST /v1/customers/:id`: ```json {"id": "req_001", "path_params": {"id": "cus_1AbCdEfGhIjKlMn"}, "params": {"name": "Jenny Rosen", "email": "jenny@example.com"}} {"id": "req_002", "path_params": {"id": "cus_2BcDeFgHiJkLmNo"}, "params": {"name": "John Smith", "metadata": {"tier": "premium"}}} {"id": "req_003", "context": "acct_1234567890", "path_params": {"id": "cus_3CdEfGhIjKlMnOp"}, "params": {"description": "Updated by batch"}} ``` #### API-Methode - POST /v1/subscriptions/:id/migrate Für den Endpoint `POST /v1/subscriptions/:id/migrate`: ```json {"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"billing_cycle_anchor": "unchanged", "proration_behavior": "none"}} {"id": "req_002", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"billing_cycle_anchor": "unchanged", "proration_behavior": "create_prorations"}} ``` #### API-Methode - POST /v1/subscriptions/:id Für den Endpoint `POST /v1/subscriptions/:id`: ```json {"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"description": "Updated subscription description"}} {"id": "req_002", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"migration_batch": "v2"}}} {"id": "req_003", "path_params": {"id": "sub_3CdEfGhIjKlMnOp"}, "params": {"cancel_at_period_end": true}} ``` #### API-Methode - POST /v1/promotion_codes Für den Endpoint `POST /v1/promotion_codes`: ```json {"id": "req_001", "params": {"coupon": "25OFF", "code": "SUMMER25"}} {"id": "req_002", "params": {"coupon": "50OFF", "code": "WINTER50", "max_redemptions": 100}} ``` #### API-Methode - POST /v1/promotion_codes/:id Für den Endpoint `POST /v1/promotion_codes/:id`: ```json {"id": "req_001", "path_params": {"id": "promo_1AbCdEfGhIjKlMn"}, "params": {"active": false}} {"id": "req_002", "path_params": {"id": "promo_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"tier": "premium"}}} ``` Jede `id` muss innerhalb der Datei eindeutig sein. Stripe verwendet sie, um Anfragen mit Ergebnissen zu verknüpfen, da die Ergebnisdatei nicht genauso geordnet ist wie die Eingabedatei. ## Auftragsstatus überwachen Sie können Ihren Batch-Auftrag nachverfolgen, indem Sie den Endpoint abfragen oder [Webhook-Ereignisse](https://docs.stripe.com/batch-api.md#webhook-events) überwachen. Wir empfehlen die Verwendung von Webhook-Ereignissen für Produktionsintegrationen. ### Status abfragen ```bash curl https://api.stripe.com/v2/core/batch_jobs/{BATCH_JOB_ID} \ -u <>: \ -H "Stripe-Version: 2026-03-25.preview" ``` Der Inhaltstyp für diese Anfrage ist eine JSON-Datei. Während der Ausführung des Auftrags enthält `status_details` Fortschrittsanzeigen in Echtzeit: ```json { "status": "in_progress", "status_details": { "in_progress": { "success_count": "1", "failure_count": "0" } } } ``` Während der Phase `validating` ist in `status_details` ein Feld `validated_count` enthalten, das angibt, wie viele Zeilen Stripe bisher validiert hat. Batch-Auftrag-API-Aufrufe werden im Stripe-Dashboard oder in den Workbench-Anfrageprotokollen angezeigt. Die zugrunde liegenden API-Aufrufe werden nicht in den Anfrageprotokollen angezeigt. Verwenden Sie den Abruf-Endpoint oder Webhook-Ereignisse, um den Fortschritt zu überwachen. Um Fehler bei einzelnen Anfragen zu beheben, überprüfen Sie die Ergebnisdatei. ### Lebenszyklus des Auftrags Nachdem Sie die Eingabedatei hochgeladen haben, durchläuft der Batch-Auftrag die folgenden Statusphasen: | Status | Beschreibung | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | | `ready_for_upload` | Der Batch-Auftrag wurde erstellt und wartet auf die Eingabedatei. | | `validating` | Die Eingabedatei wurde hochgeladen und Stripe validiert sie. Wird übersprungen, wenn `skip_validation` `true` ist. | | `in_progress` | Validierung übergeben (oder übersprungen) und Stripe verarbeitet die Anfragen. | | `complete` | Alle Anfragen wurden bearbeitet. Die Ergebnisse können heruntergeladen werden. | | `cancelling` | Eine Stornierung wurde angefordert. Stripe schließt die laufenden Anfragen ab. | ### Terminal-Status | Status | Beschreibung | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `validation_failed` | Die Eingabedatei enthält Fehler. Es wurden keine Anfragen verarbeitet. Überprüfen Sie das Batch-Auftrags-Objekt auf Fehlerdetails. Dies gilt nur für `skip_validation: false`. | | `batch_failed` | Während der Verarbeitung ist ein unerwarteter Fehler aufgetreten. | | `Storniert` | Der Batch-Auftrag wurde storniert. Teilergebnisse sind möglicherweise verfügbar. | | `upload_timeout` | Die Upload-URL ist abgelaufen, bevor die Datei hochgeladen wurde. Erstellen Sie einen neuen Batch-Auftrag. | | `timeout` | Der Batch-Auftrag hat die maximale Bearbeitungsdauer von 24 Stunden überschritten. Teilergebnisse sind möglicherweise verfügbar. | ### Validierung Wenn `skip_validation` `false` ist (Standardeinstellung), validiert Stripe die gesamte Eingabedatei, bevor Anfragen verarbeitet werden. Diese Validierung erfasst Fehler wie: - Ungültige JSON in einer beliebigen Zeile. - Fehlende oder ungültige `id`-Felder. - Doppelte IDs. - Fehlende erforderliche `path_params` für den Ziel-Endpoint. - Falsch formatierte Parameter. Wenn die Validierung fehlschlägt, ändert sich der Status in `validation_failed` und Stripe versucht keine Anfragen. Das Batch-Auftrags-Objekt enthält Details zum ersten aufgetretenen Fehler. Wenn `skip_validation` `true` ist, wechselt der Job nach dem Hochladen direkt von `ready_for_upload` zu `in_progress`. Bei Fehlern in einzelnen Anfragen wird nicht der gesamte Batch blockiert, sondern die Fehler werden in der Ergebnisdatei angezeigt. ## Ergebnisse herunterladen Wenn der Batch-Auftrag den Status `complete` erreicht, enthält das Feld `status_details` eine Zusammenfassung der Erfolge und Fehler sowie eine vorsignierte URL, die für die Ausgabedatei heruntergeladen wird: ```json { "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz", "object": "v2.core.batch_job", "created": "2026-03-09T20:55:31.000Z", "maximum_rps": 10, "skip_validation": true, "status": "complete", "status_details": { "complete": { "success_count": "2", "failure_count": "0", "output_file": { "content_type": "application/jsonlines", "size": "8514", "download_url": { "expires_at": "2026-03-09T22:05:31.000Z", "url": "https://stripeusercontent.com/files/download/..." } } } } } ``` Laden Sie die Datei mit der URL in `status_details.complete.output_file.download_url.url` herunter. Stripe stellt eine Ausgabedatei bereit, wenn der Batch-Auftrag eine der folgenden Statusphasen erreicht: - `complete` - `Storniert` - `timeout` - `validation_failed` Im Feld `expires_at` können Sie sehen, wann die Frist der heruntergeladenen URL abläuft. Die Ergebnisdatei enthält sowohl erfolgreiche als auch fehlgeschlagene Anfragen in einer einzelnen Datei. Um Fehler zu finden, filtern Sie nach Zeilen, in denen der `status` nicht `200` ist. ### Ergebnisdateiformat Die Ausgabedatei verwendet das JSONL-Format (ein JSON-Objekt pro Zeile). Jede Zeile enthält die folgenden Felder: | Feld | Beschreibung | | ---------- | --------------------------------------------------------------------------------------------------------- | | `id` | Die ID der Anfrage aus der Eingabedatei. Verwenden Sie diese, um Ergebnisse mit Anfragen zu verknüpfen. | | `response` | Das vollständige API-Antwortobjekt. Enthält im Erfolgsfall die Ressource, im Fehlerfall ein Fehlerobjekt. | | `status` | Der HTTP-Statuscode als ganze Zahl (z. B. `200`, `402`). | ### Beispiel-Ergebnisdatei Erfolgreiche Anfragen geben die vollständige API-Ressource im `response` zurück: ```json {"id": "req_001", "response": {"id": "sub_1AbCdEfGhIjKlMn", "object": "subscription", "status": "active", "billing_cycle_anchor": 1710021331, "current_period_end": 1712613331, "current_period_start": 1710021331}, "status": 200} {"id": "req_002", "response": {"id": "sub_2BcDeFgHiJkLmNo", "object": "subscription", "status": "active", "billing_cycle_anchor": 1710021331, "current_period_end": 1712613331, "current_period_start": 1710021331}, "status": 200} ``` Fehlgeschlagene Anfragen geben ein Fehlerobjekt zurück: ```json {"id": "req_003", "response": {"error": {"message": "This subscription cannot be migrated because it is not active. Current status is canceled.", "type": "invalid_request_error", "code": "resource_invalid_state"}}, "status": 400} ``` Die Ergebnisse werden nicht in der gleichen Reihenfolge zurückgegeben wie in der Eingabedatei. Verwenden Sie das Feld `id`, um die Ergebnisse mit der entsprechenden Anfrage abzugleichen. ## Batch-Auftrag stornieren Sie können einen Batch-Auftrag, der noch nicht abgeschlossen ist, stornieren, indem Sie eine `POST`-Anfrage senden: ```bash curl https://api.stripe.com/v2/core/batch_jobs/{BATCH_JOB_ID}/cancel \ -u <>: \ -X POST \ -H "Stripe-Version: 2026-03-25.preview" ``` Die Stornierung erfolgt asynchron. Der Auftrag wechselt zunächst zu `cancelling`, während laufende Anfragen abgeschlossen werden, und dann zu `cancelled`. Alle Teilergebnisse aus Anfragen, die vor der Stornierung verarbeitet wurden, sind in der Ergebnisdatei verfügbar. ## Webhook-Ereignisse Batch-Aufträge erzeugen für jeden Zustandswechsel v2 Thin-Ereignisse. Um diese Ereignisse zu empfangen, müssen Sie ein [v2-Ereignisziel](https://docs.stripe.com/event-destinations.md) konfigurieren. Batch-Auftrags-Ereignisse erfordern v2-Ereignisziele. Sie werden nicht an v1 Webhook-Endpoints übermittelt. Folgende Ereignisse sind verfügbar: | Ereignistyp | Beschreibung | | ------------------------------------- | -------------------------------------------------------------------- | | `v2.core.batch_job.created` | Ein Batch-Auftrag wurde erstellt. | | `v2.core.batch_job.ready_for_upload` | Der Batch-Auftrag kann jetzt hochgeladen werden. | | `v2.core.batch_job.validating` | Datei-Upload abgeschlossen, Validierung läuft. | | `v2.core.batch_job.validation_failed` | Validierung der Eingabedatei fehlgeschlagen. | | `v2.core.batch_job.completed` | Alle Anfragen wurden verarbeitet. | | `v2.core.batch_job.batch_failed` | Der Batch-Auftrag ist unerwartet fehlgeschlagen. | | `v2.core.batch_job.canceled` | Der Batch-Auftrag wurde abgebrochen. | | `v2.core.batch_job.timeout` | Der Batch-Auftrag hat die maximale Verarbeitungsdauer überschritten. | | `v2.core.batch_job.upload_timeout` | Die Upload-URL ist abgelaufen, bevor die Datei hochgeladen wurde. | | `v2.core.batch_job.updated` | Der Status oder Fortschritt des Batch-Auftrags hat sich geändert. | Alle Batch-Auftrags-Ereignisse enthalten die Metadaten, die Sie beim Erstellen des Auftrags angegeben haben. Verwenden Sie diese, um Ereignisse mit Ihren internen Systemen zu verknüpfen. Wenn `notification_suppression` auf `{"scope": "all"}` festgelegt ist, werden Webhooks aus den zugrunde liegenden API-Vorgängen (z. B. Abonnementaktualisierungsereignisse) unterdrückt. Die oben aufgeführten Batch-Ereignisse werden unabhängig von dieser Einstellung immer zugestellt. ## Häufige Fehler ### Upload-URL abgelaufen Wenn Sie die Eingabedatei nicht vor dem Zeitstempel `expires_at` (5 Minuten nach Auftragserstellung) hochladen, wechselt der Batch-Auftrag in den Status `upload_timeout`. Erstellen Sie einen neuen Batch-Auftrag und laden Sie die Datei umgehend hoch. Generieren Sie Ihre Eingabedatei, bevor Sie den Batch-Auftrag erstellen, um dies zu vermeiden. ### Ungültiger Ressourcenstatus Einzelne Anfragen können fehlschlagen, wenn sich die Zielressource nicht im erwarteten Zustand befindet. Beispiel: Bei Verwendung von `/v1/subscriptions/:id/migrate`: - **Abonnement ist nicht aktiv**: Das Abonnement muss sich im Zustand `active` befinden, bevor Sie es migrieren können. Stornierte oder nicht abgeschlossene Abonnements geben den Fehler `400` mit `resource_invalid_state` zurück. - **Abonnement bereits migriert**: Der Versuch, ein bereits migriertes Abonnement zu migrieren, gibt einen Fehler zurück. Diese Fehler pro Anfrage erscheinen in der Ergebnisdatei mit einem Statuscode ungleich `200`. Der Batch-Auftrag selbst wird immer noch erfolgreich abgeschlossen (der Batch wird weiter verarbeitet, wenn einzelne Zeilen fehlschlagen). ### Pfadparameter stimmt nicht überein Die Schlüssel in `path_params` müssen genau mit den Platzhaltern im Endpoint-Pfad übereinstimmen. Wenn Ihr Endpoint-Pfad beispielsweise `/v1/subscriptions/:id/migrate` ist, müssen Ihre `path_params` `{"id": "sub_..."}` verwenden. Eine Abweichung zwischen dem Platzhalternamen und dem Schlüssel verursacht einen Validierungsfehler oder einen Statuscode `400` in der Ergebnisdatei. ### Inhaltstyp hochladen Die Upload-`PUT`-Anfrage muss den `Content-Type: application/octet-stream` enthalten. Andere Inhaltstypen werden abgelehnt. ### Dateiformatfehler Wenn `skip_validation` `falsch` ist, führen diese Fehler dazu, dass der gesamte Batch mit dem Status `validation_failed` fehlschlägt: - Zeilen, die kein gültiges JSON sind - Fehlendes `id`-Feld in einer beliebigen Zeile - `id-`-Werte zeilenübergreifend duplizieren - IDs, die Zeichen außerhalb von `A-Za-z0-9_-` enthalten Wenn `skip_validation` `true` ist, können Formatfehler auf Dateiebene dazu führen, dass einzelne Zeilen fehlschlagen; es wird nicht der gesamte Batch blockiert. ### Zeitüberschreitung bei der Auftragsverarbeitung Batch-Aufträge, die länger als 24 Stunden ausgeführt werden, gehen in den Status `timeout` über. Teilergebnisse aus Anfragen, die vor der Zeitüberschreitung abgeschlossen wurden, sind in der Ergebnisdatei verfügbar. ## Best Practices ### Wählen Sie die richtige `maximum_rps` Der Parameter `maximum_rps` steuert, wie schnell Stripe Anfragen in Ihrem Batch verarbeitet. Bei der Batch-Verarbeitung wird ein separates Begrenzungskontingent für Ihre normalen API-Anfragen verwendet, sodass Batch-Aufträge den regulären API-Datenverkehr Ihres Kontos nicht beeinträchtigen. - **Niedrigere Werte**: 1–10 eignen sich für nicht zeitkritische Massenverarbeitungen. - **Höhere Werte**: 50–100 verarbeiten Batches schneller und eignen sich für unabhängige Prozesse über verschiedene Ressourcen hinweg. ### Validierung für kritische Vorgänge verwenden Lassen Sie `skip_validation` auf `false` (Standard) für Vorgänge, bei denen eine Teilverarbeitung zu Problemen führen würde. Durch die Validierung wird sichergestellt, dass Ihre gesamte Datei ordnungsgemäß formatiert ist, bevor Anfragen ausgeführt werden. Setzen Sie `skip_validation` auf `true`, wenn Sie Ihre Eingabedaten bereits validiert haben und den Auftrag schneller starten möchten oder wenn die Verarbeitung von Teilergebnissen akzeptabel ist. ### Große Workloads aufteilen Wenn Ihre Eingabedatei größer als 5 GB ist, teilen Sie den Arbeitsaufwand in mehrere Batch-Aufträge auf. Sie können mehrere Batch-Aufträge gleichzeitig ausführen. ### Ressourcenstatus vor dem Start der Batchverarbeitung verifizieren Bestätigen Sie, dass sich alle Zielressourcen im erforderlichen Zustand befinden, bevor Sie einen Batch übermitteln. Beispielsweise müssen Abonnements aktiv sein, bevor sie mit `/v1/subscriptions/:id/migrate` migriert werden können. Batch-Aufträge führen die Zieloperation direkt aus und ändern den Ressourcenstatus nicht als Voraussetzung. ### Umgang mit Fehlern in den Ergebnissen Überprüfen Sie immer das Feld `status` in jeder Ergebniszeile. Einzelne Anfragen innerhalb eines erfolgreichen Batches können immer noch fehlschlagen (z. B. aufgrund unzureichender Gelder oder ungültiger Parameter). Integrieren Sie Ihre Lösung so, dass die Ergebnisdatei nach Statusmeldungen ungleich `200` gefiltert und Fehler entsprechend gehandhabt werden. ### Bereiten Sie Ihre Datei vor, bevor Sie den Auftrag erstellen Die Upload-URL läuft 5 Minuten nach Erstellung des Batch-Auftrags ab. Generieren und validieren Sie Ihre Eingabedatei, bevor Sie den Create-Endpoint aufrufen. Wenn Sie Daten dynamisch vorbereiten müssen, schließen Sie zuerst den gesamten Datenabruf und die Dateigenerierung ab, erstellen Sie dann den Batch-Auftrag und laden Sie ihn sofort hoch.