---
title: API-Grundlagen
description: Basis-URL, Berechtigungen von API-Schlüsseln, Fehlerliste, Ratenlimits, Idempotenz-Schlüssel und Paginierung der BillionSend-API.
seo:
  title: API-Authentifizierung und Fehler
ai:
  exclude: true
---

Die Endpunktseiten in der [API-Referenz](/docs/de/api-reference) werden aus den Routendefinitionen der API erzeugt. Die [OpenAPI-3.1-Spezifikation](/docs/api.openapi.json) ist dieselbe Quelle als eine JSON-Datei.

Die API ist kompatibel mit der Resend-API: gleiche Pfade, gleiche Anfrageformen und gleiches Fehlerformat. Rufen Sie sie über die BillionSend-[SDKs](/docs/de/sdks) oder per einfachem HTTP auf.

## Basis-URL

`https://api.billionsend.com`

## Authentifizierung

Senden Sie bei jeder Anfrage einen API-Schlüssel aus **API-Schlüssel** im Dashboard:

```
Authorization: Bearer bs_...
```

Ein fehlender oder fehlerhafter Schlüssel antwortet mit `401 missing_api_key`, ein falscher mit `401 invalid_api_key`.

Ein Schlüssel hat eine Berechtigungsstufe:

- **Vollzugriff** kann jeden Endpunkt nutzen.
- **Nur Versand** kann ausschließlich senden. Alles außerhalb von `/emails` antwortet mit `403 restricted_api_key`, ebenso `GET /emails`, `GET /emails/{id}`, `GET /emails/metrics`, `DELETE /emails/{id}` und jeder Endpunkt unter `/emails/receiving`, weil sie gespeicherte Inhalte zurückgeben.

Ein Schlüssel lässt sich außerdem auf **eine Domain** oder auf **ein [Postfach](/docs/de/inboxes)** beschränken. Ein auf eine Domain beschränkter Schlüssel arbeitet innerhalb dieser Domain: Er sendet nur von ihr, liest nur ihre E-Mails, sieht und ändert unter `/domains` nur sie und antwortet bei allem, was zum gesamten Team gehört (Webhooks, Sperrlisten, Vorlagen, Kontakteigenschaften, `/usage`, `/deliverability`, Verifizierungen, `POST /domains`), mit `403 restricted_api_key`; siehe [API-Schlüssel](/docs/de/api-keys). Ein Schlüssel, den Sie mit der API erstellen, ist nie umfassender als der Schlüssel, der ihn erstellt hat.

Ein Team kann 25 aktive Schlüssel haben. Welche Aktionen einen Schlüssel von einem Inhaber oder Admin erfordern, steht unter [Teamrollen](/docs/de/team-roles).

## Fehler

Jeder Fehler hat diese Form:

```json
{ "statusCode": 422, "name": "validation_error", "message": "..." }
```

| Status und Name | Bedeutung |
| --- | --- |
| `400 invalid_parameter` | Der Body ist kein gültiges JSON. |
| `401 missing_api_key` / `invalid_api_key` | Kein Schlüssel oder ein falscher. |
| `403 restricted_api_key` | Die Berechtigung oder der Geltungsbereich des Schlüssels erlaubt dies nicht. |
| `403 forbidden` | Ihre Rolle oder Ihr Schlüssel erlaubt diese Aktion nicht. |
| `403 plan_limit_reached` | Sie haben ein Limit Ihres Tarifs erreicht. Siehe [Tarife und Limits](/docs/de/billing). |
| `403 sending_paused` | Der Versand ist pausiert, weil Ihre Bounce- oder Beschwerderate zu hoch ist. |
| `404 not_found` | Der Endpunkt oder das Angeforderte existiert nicht. |
| `409 invalid_idempotent_request` | Der Idempotenz-Schlüssel wurde mit einem anderen Payload verwendet. |
| `415` | Der Body ist nicht `application/json`. |
| `422 validation_error` | Die Anfrage ist ungültig. Die Meldung nennt den Grund. |
| `422 all_recipients_suppressed` | Jeder Empfänger ist gesperrt oder abgemeldet. Siehe [Sperrliste](/docs/de/concepts/suppressions). |
| `429 rate_limit_exceeded` | Zu viele Anfragen. |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | Das Sendekontingent Ihres Tarifs ist aufgebraucht. Siehe [Tarife und Limits](/docs/de/billing). |
| `503 service_unavailable` | Der Statistikspeicher hat nicht geantwortet. Der Versand ist nicht betroffen. |

Jedes `429` trägt einen `retry-after`-Header: die Sekunden, die Sie warten müssen.

Jede Antwort, ob Fehler oder nicht, trägt einen `x-request-id`-Header: die ID der Anfrage, dieselbe ID, die die Anfrage auf der Seite „Logs“ des Dashboards hat. Nennen Sie sie, wenn Sie uns zu einer Anfrage fragen.

Ein Empfänger, dessen Domain nie E-Mails empfangen kann, etwa `x@example.com`, `x@foo.test` oder `x@gmail.con`, wird mit `422 validation_error` abgelehnt. Dasselbe gilt für einen neuen Kontakt mit einer solchen Adresse. Um zu testen, ohne jemandem zu schreiben, senden Sie an `success@simulator.amazonses.com`.

[Empfang](/docs/de/receiving), [Postfächer](/docs/de/inboxes) und [Agent-Sicherheit](/docs/de/agent-safety) bringen eigene Fehler mit, die diese Seiten auflisten.

## Ratenlimits

Jeder API-Schlüssel kann 600 Anfragen pro Minute stellen, die Schlüssel eines Teams zusammen 3.000. Über dem Limit erhalten Sie `429 rate_limit_exceeded` und einen `retry-after`-Header. Mehr als 20 fehlgeschlagene Authentifizierungen pro Minute von einer IP-Adresse werden auf dieselbe Weise abgelehnt.

## Idempotenz

`POST /emails` und `POST /emails/batch` akzeptieren einen `Idempotency-Key`-Header mit 1 bis 256 Zeichen. Das gilt auch für Antworten, Weiterleitungen und Entwurfsversand bei Postfächern sowie für Antworten und Weiterleitungen empfangener E-Mails. Wiederholen Sie die Anfrage mit demselben Schlüssel und demselben Payload, erhalten Sie die ursprüngliche Antwort statt einer zweiten E-Mail. Derselbe Schlüssel mit einem anderen Payload antwortet mit `409`.

## Paginierung

Listenendpunkte akzeptieren `limit` (1 bis 100, Standard 20) und die Cursor `after` und `before`, jeweils eine Element-ID aus einer früheren Seite. Die Antwort enthält `has_more`. Listen laufen von neu nach alt:

- `after` nimmt die letzte ID einer Seite und liefert ältere Elemente.
- `before` nimmt die erste ID und liefert neuere Elemente.

Um sich über Neues auf den Stand zu bringen, übergeben Sie die neueste gespeicherte ID als `before`.

Einige Listen laufen in anderer Reihenfolge, was ihre Referenzseiten angeben: Postfach-Threads (letzte Aktivität zuerst), E-Mails eines Threads (älteste zuerst) sowie Themen und Labels (älteste zuerst, alle auf einmal). Ein Cursor, der auf kein Element passt, antwortet mit `422 validation_error` (`404` unter `/inboxes`).

## Gut zu wissen

- **Anhänge** akzeptieren nur Inline-Base64-`content`. Eine entfernte `path`-URL antwortet mit `422`. Anhänge ergeben zusammen bis zu 10 MiB pro E-Mail, und die gesamte E-Mail muss unter 40 MB bleiben. Programme und Skripte (`.exe`, `.js`, `.bat` und Ähnliches, auch innerhalb einer ZIP-Datei) werden immer abgelehnt. Bei einem neuen Team werden einige riskante Typen, etwa Archive, Webseiten und Office-Dateien mit Makros, angenommen, warten aber vor dem Versand auf eine Prüfung.
- **Kontakte** gehören zum Team. Es gibt keine Audiences: Die Audience-Endpunkte funktionieren als Aliase für [Segmente](/docs/de/concepts/segments).
- **Abmeldungen** gehören zur Absenderdomain. Siehe [Abmeldungen](/docs/de/concepts/unsubscribes).
- **Empfänger**: `to`, `cc` und `bcc` zusammen nehmen bis zu 50 Adressen auf, jede ein einzelnes Postfach. Ein Versand, bei dem jede `to`-Adresse gesperrt ist, antwortet mit `422 all_recipients_suppressed`.
- **Header** unterliegen einer Positivliste: jeder `X-*`-Name (außer `X-SES-*` und `X-BillionSend-*`), Threading- und Prioritäts-Header sowie das `List-Unsubscribe`-Paar. Alles andere antwortet mit `422`.
- **Betreffzeilen** dürfen bis zu 998 Zeichen lang sein.
- **Zusätzliche Endpunkte**: `GET /usage` (Tarif, Limits und Nutzung), `DELETE /emails/{id}` und `GET /emails/metrics` ([Analysen](/docs/de/concepts/analytics)).
- **Massenoperationen bei Kontakten**: `POST /contacts/batch` legt an und `POST /contacts/batch/remove` löscht bis zu 1.000 Kontakte in einer Anfrage. `include=properties,topics` bei den Kontaktlisten ergänzt die Eigenschaften und Themen jedes Kontakts.
- **Massenoperationen bei Sperren** akzeptieren bis zu 1.000 Adressen pro Anfrage.
- **Zusätzliche Status**: Newsletter-Versände können `canceled` sein.
- **Empfang und Postfächer** sind in der Beta, mit Long-Polling und einem Live-Ereignisstrom für neue E-Mails. Siehe [Empfang](/docs/de/receiving) und [Postfächer](/docs/de/inboxes).
- **Nicht unterstützte** Einstellungen werden mit `422` abgelehnt, statt stillschweigend ignoriert zu werden.

## Signierte Download-Links

Empfangene E-Mails tragen Download-Links für die Rohnachricht und ihre Anhänge. Es sind einfache `GET`-URLs, die keinen API-Schlüssel brauchen, eine Stunde lang gelten und nach Ablauf mit `403` antworten. Fragen Sie die API erneut nach einem neuen Link. Siehe [Empfang](/docs/de/receiving).
