Zum Inhalt springen
Checkliste

Go-live-Checkliste

Bevor die erste echte Rechnung rausgeht: acht Punkte, die eine Integration abdecken sollte. Jeder Punkt verweist auf die Seite, auf der die Einzelheiten stehen.

Die acht Punkte

  1. 1

    Live-Key einsetzen

    Ersetze sk_test_… durch sk_live_…. Host, Pfade und Antworten bleiben gleich; das Präfix ändert am Verhalten der API nichts. Beide Keys zählen gegen dasselbe Monatskontingent.

    Mehr dazu
  2. 2

    Key nur aus der Umgebung lesen

    Der Key gehört in eine Umgebungsvariable oder einen Secret Manager, nie in den Code, den Query-String oder den Request-Body. Gesendet wird er im Authorization-Header als Bearer-Token.

    Mehr dazu
  3. 3

    Zwei Arten von 429 unterscheiden

    Trägt die Antwort ein quota-Objekt (QUOTA_EXCEEDED), ist das Monatskontingent aufgebraucht: kein Retry. Ohne quota-Objekt greift das Rate Limit: mit exponentiellem Backoff wiederholen, denn einen Retry-After-Header gibt es dabei nicht.

    Mehr dazu
  4. 4

    Bei 503 Retry-After beachten

    Antworten wie SERVER_BUSY (5 Sekunden) oder EMBED_UNAVAILABLE (60 Sekunden) nennen im Retry-After-Header, wie lange du warten sollst. Abgerechnet wird dabei nichts.

    Mehr dazu
  5. 5

    4xx nicht wiederholen

    Ein 400 oder 422 behebst du in den Daten, nicht durch einen zweiten Versuch. Bei 422 nennt errors[] die verletzte Regel.

    Mehr dazu
  6. 6

    Doppelte Rechnungen selbst erkennen

    Die API hat keinen Idempotency-Key-Header. Jede Erzeugungs-Antwort trägt aber payloadHash, einen SHA-256 über das kanonische JSON deiner Rechnungsdaten: gleiche Daten, gleicher Wert. Speichere ihn mit der Rechnung und prüfe vor einem erneuten Aufruf, ob es ihn schon gibt. hash taugt dafür nicht, er wechselt bei jedem Aufruf.

    Mehr dazu
  7. 7

    Request-Kennung loggen

    Jede Antwort trägt x-request-id. Schreib sie zu jedem Fehler ins Log, mit ihr findet der Support deinen Aufruf.

    Mehr dazu
  8. 8

    Tarif zum Volumen prüfen

    Der Preisrechner zeigt, welcher Tarif zu deinem monatlichen Rechnungsvolumen passt und was er kostet.

    Mehr dazu

Alles zusammen: ein Aufruf mit Retry

Wiederholt nur, was ein Retry beheben kann, wartet so lange, wie Retry-After sagt, und gibt die Request-Kennung im Fehler mit.

javascript
1async function callInvoiceApi(url, body, attempts = 4) {
2  for (let i = 0; i < attempts; i++) {
3    const res = await fetch(url, {
4      method: "POST",
5      headers: {
6        Authorization: `Bearer ${process.env.INVOICE_API_KEY}`,
7        "Content-Type": "application/json",
8      },
9      body: JSON.stringify(body),
10    });
11    if (res.ok) return res.json();
12 
13    const requestId = res.headers.get("x-request-id");
14    const err = await res.json().catch(() => ({}));
15 
16    // 429 with a quota object = monthly quota used up: retrying cannot help.
17    // 429 without it = rate limit. 5xx = try again. 4xx = fix the data.
18    const retryable = (res.status === 429 && !err.quota) || res.status >= 500;
19    if (!retryable || i === attempts - 1) {
20      throw new Error(`${res.status} ${err.error ?? ""} (request ${requestId})`);
21    }
22 
23    // 503 SERVER_BUSY / EMBED_UNAVAILABLE say how long to wait; otherwise back off.
24    const retryAfter = Number(res.headers.get("retry-after"));
25    const waitMs = retryAfter > 0 ? retryAfter * 1000 : 2 ** i * 1000;
26    await new Promise((resolve) => setTimeout(resolve, waitMs));
27  }
28}

Noch nicht so weit?

Der Quickstart bringt dich mit einem Test-Key in fünf Minuten zur ersten Rechnung.

Zum Quickstart