# Rate Limits & Fehlerbehandlung

Eine gute API-Integration rechnet mit Fehlern, Überlast und zeitweiser Nicht-Erreichbarkeit. Hier die Spielregeln von SendDrop.

***

### Rate Limits

| Tarif | Anfragen pro Minute    |
| ----- | ---------------------- |
| Plus  | 60                     |
| Pro   | 300                    |
| Ultra | 1000+ (konfigurierbar) |

{% hint style="info" %}
Der **Free-Tarif** hat keinen API-Zugang. Für API-Nutzung ist mindestens der **Plus-Tarif** nötig.
{% endhint %}

Bei Überschreitung bekommen Sie **HTTP 429 Too Many Requests**:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retryAfterSeconds": 12
  }
}
```

Der Header `Retry-After` gibt die Wartezeit in Sekunden an.

#### Empfehlung

* **Exponential Backoff** mit Jitter: bei 429 warten Sie `retryAfterSeconds` plus einen kleinen Zufall.
* **Parallele Requests begrenzen**: lieber ein Pool aus z. B. 5 gleichzeitigen Requests als 50.
* **Batch-Endpoints nutzen** (sofern vorhanden): weniger Requests für dieselbe Arbeit.

***

### HTTP-Status-Codes

| Code    | Bedeutung           | Typische Ursache                                        |
| ------- | ------------------- | ------------------------------------------------------- |
| **200** | OK                  | Erfolg                                                  |
| **201** | Created             | Ressource erzeugt                                       |
| **400** | Bad Request         | Validierungsfehler                                      |
| **401** | Unauthorized        | Token fehlt oder ungültig                               |
| **403** | Forbidden           | Token ohne Rechte für diese Aktion                      |
| **404** | Not Found           | Ressource existiert nicht (oder nicht Ihre)             |
| **409** | Conflict            | Zustands-Konflikt (z. B. Bestellung bereits storniert)  |
| **422** | Unprocessable       | Geschäftsregel verletzt (z. B. Carrier nicht verfügbar) |
| **429** | Too Many Requests   | Rate Limit                                              |
| **500** | Server Error        | Unerwarteter Fehler bei SendDrop                        |
| **503** | Service Unavailable | Wartung oder Überlast                                   |

***

### Fehler-Struktur

Alle Fehler folgen einem einheitlichen Schema:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'recipient.zip' is required",
    "fields": {
      "recipient.zip": "required"
    },
    "traceId": "trc_5a6b7c"
  }
}
```

* **`code`**: Stabil, maschinenlesbar.
* **`message`**: Für Menschen, kann sich ändern.
* **`fields`**: Bei Validierungsfehlern: konkret betroffene Felder.
* **`traceId`**: Geben Sie die im Support an – damit finden wir den Request sofort.

***

### Typische Fehler-Codes

| `code`                        | Bedeutung                                            | Lösung                         |
| ----------------------------- | ---------------------------------------------------- | ------------------------------ |
| `UNAUTHORIZED`                | Token fehlt/ungültig                                 | Token prüfen                   |
| `VALIDATION_ERROR`            | Pflichtfeld fehlt oder Format falsch                 | `fields` prüfen                |
| `CARRIER_NOT_AVAILABLE`       | Carrier nicht aktiviert oder Service nicht verfügbar | Anderen Carrier/Service wählen |
| `QUOTA_EXCEEDED`              | Tarif-Limit erreicht                                 | Tarif upgraden                 |
| `DUPLICATE_EXTERNAL_ORDER_ID` | `externalOrderId` bereits vergeben                   | Anderen Key oder Idempotency   |
| `ORDER_ALREADY_CANCELED`      | Stornierung nicht möglich                            | Status prüfen                  |

***

### Retry-Strategie

Für **sichere Retries**:

* **500 / 503 / 429**: Retry mit exponential Backoff (z. B. 1 s, 2 s, 4 s, 8 s, max 60 s).
* **400 / 422**: Nicht retriggern – Input ist fehlerhaft, Code muss angepasst werden.
* **401 / 403**: Nicht retriggern – Token-Problem, Admin-Aktion nötig.
* **409**: Nur retriggern, wenn Sie den Zustand angepasst haben.

Bei Create-Requests (z. B. Bestellung, Label): **Idempotency-Key** senden, sodass Retries keine Duplikate erzeugen:

```http
Idempotency-Key: shop-order-2026-00123
```

***

### Monitoring-Empfehlung

Loggen Sie mindestens:

* **HTTP-Status**
* **`error.code`** und **`traceId`**
* **Request-Dauer**
* **Endpoint + Methode**

Bei wiederkehrenden 5xx oder ungewöhnlich vielen 4xx: Alarm einrichten und uns informieren.

***

### Support

Bei Fragen zu API-Fehlern: E-Mail an <support@senddrop.com> mit:

* **`traceId`**,
* **Request-URL + Methode**,
* **Zeitpunkt** (+ Zeitzone),
* **Erwartetes Verhalten**.

So können wir den Fall in Minuten analysieren.

***

### Siehe auch

{% content-ref url="/pages/ZFJXurN97mu1mgXyHzat" %}
[SendDrop REST-API: Überblick](/10.-entwickler-and-integrationen/rest-api-ueberblick.md)
{% endcontent-ref %}

{% content-ref url="/pages/3s9tgw337yBnpQTomtoS" %}
[API-Token erstellen & verwalten](/10.-entwickler-and-integrationen/api-token.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.senddrop.com/10.-entwickler-and-integrationen/rate-limits-fehler.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.