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/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.

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

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
Modul publicApi: aus	403API_MODULE_DISABLEDModul zuerst, Stufe egal	403API_MODULE_DISABLEDModul zuerst, Stufe egal	403API_MODULE_DISABLEDModul zuerst, Stufe egal
Modul publicApi: an	401UNAUTHENTICATEDwie jeder ungültige Schlüssel	403FORBIDDENnur bei Schreibaufrufen, Lesen läuft	2xxAufruf 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

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

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"
}