---
title: "Fehler"
description: "Jede Fehlerantwort ist application/problem+json nach RFC 9457. Der code ist der Vertrag, type zeigt auf seine Seite in diesem Portal."
lang: de
url: https://developers.bodo-app.com/guides/errors/
apiVersion: 2026-11-01
---

# Fehler

Jede Fehlerantwort ist application/problem+json nach RFC 9457. Der code ist der Vertrag, type zeigt auf seine Seite in diesem Portal.

## Aufbau einer Fehlerantwort

Verzweige im Client auf `code`, nie auf den Text. Bei Supportfragen nennst du die `requestId`.

**POST /v1/contacts**

```http
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: de
Request-Id: req_01JBA7Q2M4X9C3T8V5N6K1W0PZ

{
  "type": "https://developers.bodo-app.com/problems/VALIDATION_FAILED",
  "title": "Validierung fehlgeschlagen",
  "status": 422,
  "detail": "Ein Feld hat einen ungültigen Wert.",
  "instance": "/v1/contacts",
  "code": "VALIDATION_FAILED",
  "requestId": "req_01JBA7Q2M4X9C3T8V5N6K1W0PZ",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Keine gültige E-Mail-Adresse."
    }
  ]
}
```

`title` und `detail` gibt es auf Deutsch und Englisch, je nach `Accept-Language`. Mehr dazu unter [Sprache](/guides/language/).

## Codes

Jede Antwort trägt `Request-Id` im Header und `requestId` im Body, auch bei 401, 429 und 500.

| Lage | Status · Code |
| --- | --- |
| Eingabe | [400 INVALID_REQUEST](/problems/INVALID_REQUEST/) · [422 VALIDATION_FAILED](/problems/VALIDATION_FAILED/) |
| Schlüssel ungültig, abgelaufen, widerrufen, pausiert, IP nicht frei, API der Organisation aus | [401 UNAUTHENTICATED](/problems/UNAUTHENTICATED/) |
| Recht oder Scope fehlt, Organisation geschlossen oder zur Löschung vorgemerkt | [403 FORBIDDEN](/problems/FORBIDDEN/) |
| Org-Header passt nicht zum Schlüssel | [403 ORGANIZATION_MISMATCH](/problems/ORGANIZATION_MISMATCH/) |
| Modul Öffentliche API für die Organisation nicht freigeschaltet, auch für OAuth-Tokens | [403 API_MODULE_DISABLED](/problems/API_MODULE_DISABLED/) |
| Familie gesperrt, etwa Löschen, Rechnung festschreiben oder versenden | [403 RISK_FAMILY_BLOCKED](/problems/RISK_FAMILY_BLOCKED/) |
| Objekt unsichtbar oder unbekannt | [404 NOT_FOUND](/problems/NOT_FOUND/) |
| Operation nicht in der Version oder ohne Preview-Header | [404 OPERATION_NOT_IN_VERSION](/problems/OPERATION_NOT_IN_VERSION/) |
| Idempotenz | [409 IDEMPOTENCY_IN_PROGRESS](/problems/IDEMPOTENCY_IN_PROGRESS/) · [422 IDEMPOTENCY_PAYLOAD_MISMATCH](/problems/IDEMPOTENCY_PAYLOAD_MISMATCH/) |
| Version abgeschaltet | [410 VERSION_SUNSET](/problems/VERSION_SUNSET/) |
| Vorbedingung | [412 PRECONDITION_FAILED](/problems/PRECONDITION_FAILED/) · [428 PRECONDITION_REQUIRED](/problems/PRECONDITION_REQUIRED/) |
| Liste und Parameter | [400 CURSOR_MISMATCH](/problems/CURSOR_MISMATCH/) · [400 UNKNOWN_PARAMETER](/problems/UNKNOWN_PARAMETER/) |
| Dateien | [409 UPLOAD_INCOMPLETE](/problems/UPLOAD_INCOMPLETE/) · [422 UPLOAD_CHECKSUM_MISMATCH](/problems/UPLOAD_CHECKSUM_MISMATCH/) · [422 UPLOAD_REJECTED](/problems/UPLOAD_REJECTED/) |
| Batch | [400 BATCH_TOO_LARGE](/problems/BATCH_TOO_LARGE/) · [422 BATCH_FAMILY_NOT_ALLOWED](/problems/BATCH_FAMILY_NOT_ALLOWED/) |
| Webhooks | [422 WEBHOOK_URL_INVALID](/problems/WEBHOOK_URL_INVALID/) · [409 WEBHOOK_ENDPOINT_LIMIT_REACHED](/problems/WEBHOOK_ENDPOINT_LIMIT_REACHED/) |
| Drosselung | [429 RATE_LIMITED](/problems/RATE_LIMITED/) · [429 OVERLOADED](/problems/OVERLOADED/) · [429 QUOTA_EXHAUSTED](/problems/QUOTA_EXHAUSTED/) |
| API vom Betreiber pausiert (Not-Aus) | [503 API_PAUSED](/problems/API_PAUSED/) |
| Dienst dahinter | [502 UPSTREAM](/problems/UPSTREAM/) · [503 INSTANCE_PENDING](/problems/INSTANCE_PENDING/) · [500 INTERNAL](/problems/INTERNAL/) |

Alle Credential-Gründe ergeben einheitlich 401 ohne `detail`. Den genauen Grund sieht der Inhaber im Request-Log in Bodo. Alle Codes mit ihren Seiten: [Problem-Typen](/problems/).

## 403 API_MODULE_DISABLED in der Preview-Phase

Die Tür prüft zuerst das Modul publicApi der Organisation, danach die API-Stufe, die die Organisation selbst wählt.

Antwort je Modul publicApi und API-Stufe der Organisation

| Modul publicApi | API-Stufe der Organisation: aus | API-Stufe der Organisation: lesen | API-Stufe der Organisation: an |
| --- | --- | --- | --- |
| aus | 403 `API_MODULE_DISABLED`, Modul zuerst, Stufe egal | 403 `API_MODULE_DISABLED`, Modul zuerst, Stufe egal | 403 `API_MODULE_DISABLED`, Modul zuerst, Stufe egal |
| an | 401 `UNAUTHENTICATED`, wie jeder ungültige Schlüssel | 403 `FORBIDDEN`, nur bei Schreibaufrufen, Lesen läuft | 2xx, Aufruf läuft |

Ist das Modul aus, ruhen Schlüssel, Abos und Tokens. Sie werden nicht gelöscht und laufen beim Wiedereinschalten weiter. Ereignisse aus der Zeit „aus“ werden nicht nachgeliefert, der Abgleich per `updatedSince` bleibt.

## Antwort auf Deutsch

**Beispielantwort**

```http
GET /v1/contacts

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: de

{
  "type": "https://developers.bodo-app.com/problems/API_MODULE_DISABLED",
  "title": "Öffentliche API nicht freigeschaltet",
  "status": 403,
  "detail": "Für diese Organisation ist das Modul Öffentliche API nicht freigeschaltet. Dein Bodo-Ansprechpartner schaltet es frei.",
  "code": "API_MODULE_DISABLED",
  "requestId": "req_01JBF2K8N3Q7R5T9V1X4Z6B0CD"
}
```

## Antwort auf Englisch

**Beispielantwort**

```http
GET /v1/contacts · Accept-Language: en

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://developers.bodo-app.com/problems/API_MODULE_DISABLED",
  "title": "Public API not enabled",
  "status": 403,
  "detail": "The Public API module is not enabled for this organization. Your Bodo contact can enable it.",
  "code": "API_MODULE_DISABLED",
  "requestId": "req_01JBG3L9P4R8S6U0W2Y5A7C1DE"
}
```