> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehler

> Wie die Finanzberichte-API Fehler meldet: das einheitliche Format, Feldfehler in violations, die Antwort ohne Freischaltung und alle 404- und 409-Typen.

Alle Fehler kommen als `application/problem+json`. Das Feld `type` sagt maschinenlesbar, was passiert ist, `detail` enthält einen deutschen Satz, den du anzeigen kannst. Weitere Felder tragen die Werte, die zum Fehler gehören, zum Beispiel den Monat.

## Statuscodes

| Status | Bedeutung | Typ |
| - | - | - |
| `401` | Token fehlt oder ist ungültig | |
| `403` | Berechtigung fehlt | `FRAMEWORK__ACCESS_DENIED` |
| `403` | Finanzberichte nicht freigeschaltet | `https://fynn.dev/problems/feature-not-available` |
| `404` | Snapshot oder Hinweis existiert nicht oder gehört einer anderen Organisation | siehe unten |
| `409` | Die Anfrage passt nicht zum aktuellen Zustand | siehe unten |
| `422` | Ein Parameter oder Feld ist ungültig | Feldfehler in `violations` |

## Ungültige Parameter

Jeder abgelehnte Parameter steht als eigener Eintrag in `violations`, mit dem Namen in `propertyPath`, einem deutschen Satz in `message` und einem stabilen `code`. Mehrere Fehler kommen in einer Antwort.

```bash theme={null}
curl "https://coreapi.io/api/analytics/mrr-financials?from=2023-01&to=2026-09&scope=account" \
  -H "Authorization: Bearer api_DEIN_TOKEN"
```

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "Validation Failed",
  "status": 422,
  "violations": [
    {
      "propertyPath": "scope",
      "message": "Unbekannte Ebene. Erlaubt sind subscription, invoice_address, customer und organisation.",
      "code": "8e179f1b-97aa-4560-a02f-2a8b42e49df7"
    },
    {
      "propertyPath": "to",
      "message": "Der Zeitraum darf höchstens 36 Monate umfassen.",
      "code": "analytics.mrr_financials.range_too_long"
    }
  ]
}
```

Häufige Codes der Finanzberichte:

| `propertyPath` | `code` | Ursache |
| - | - | - |
| `from`, `to`, `month` | `de1e3db3-5ed4-4941-aae4-59f3667cc3a3` | Monat nicht im Format `YYYY-MM` zwischen 1900 und 2099 |
| `to` | `analytics.mrr_financials.range_reversed` | `to` liegt vor `from` |
| `to` | `analytics.mrr_financials.range_too_long` | mehr als 36 Monate |
| `month` | `c1051bb4-d103-4f74-8988-acbcafc7fdc3` | Drill-down oder Snapshot ohne Monat |
| `metric` | `c1051bb4-d103-4f74-8988-acbcafc7fdc3` | Drill-down ohne Kennzahl |
| `part` | `8e179f1b-97aa-4560-a02f-2a8b42e49df7` | anderer Wert als `reversed` oder `counter` |
| `part` | `analytics.mrr_financials.part_correction_only` | `part` bei einer anderen Kennzahl als `cash_correction` |

`scope=` ohne Wert lehnt die API als unbekannte Ebene ab (`422`). Lass den Parameter weg, dann gilt die Ebene aus den Einstellungen.

Ruft eine Anfrage einen Endpunkt ganz ohne Daten auf, etwa `POST /api/analytics/finance/snapshots` ohne Body, lautet der Typ `VALIDATION__EMPTY_PAYLOAD` und `violations` ist leer. Validierungsfehler, die erst nach dem Einsetzen der Voreinstellungen entstehen, haben den Typ `ANALYTICS_MRR_FINANCIALS__INVALID_QUERY` und dieselbe `violations`-Form. Für dein System macht das keinen Unterschied: Werte immer `violations` aus.

## Finanzberichte nicht freigeschaltet

Sind die Finanzberichte für deine Organisation noch nicht freigeschaltet, antwortet jeder Endpunkt dieser API mit `403`:

```json theme={null}
{
  "type": "https://fynn.dev/problems/feature-not-available",
  "title": "Feature not available",
  "detail": "The requested feature is not available. Please contact customer support.",
  "featureFlags": ["analytics.advanced"]
}
```

Erkenne diese Antwort an `type`. Eine fehlende Berechtigung ist davon getrennt und kommt als `FRAMEWORK__ACCESS_DENIED`.

## 404

| Typ | Wann |
| - | - |
| `ANALYTICS_FINANCE__SNAPSHOT_NOT_FOUND` | Monat oder Version des Snapshots existiert nicht |
| `ANALYTICS_MRR_FINANCIALS__FINDING_NOT_FOUND` | Der Hinweis gehört nicht zur neuesten Berechnung |

## 409

| Typ | Wann | Zusätzliche Felder |
| - | - | - |
| `ANALYTICS_MRR_FINANCIALS__SNAPSHOT_WITHOUT_BUILD` | Snapshot, bevor die erste Berechnung existiert | |
| `ANALYTICS_MRR_FINANCIALS__SNAPSHOT_BUILD_BEFORE_MONTH_END` | Snapshot, obwohl die letzte Berechnung vor dem Monatsende lief | `month` |

Ein Snapshot für einen laufenden Monat ist ein ungültiger Wert: `422` mit dem Typ `ANALYTICS_MRR_FINANCIALS__SNAPSHOT_MONTH_NOT_ENDED`, den Feldern `month` und `violations`.

Ein Beispiel für jeden Fall findest du unter [Snapshots](https://docs.fynn.eu/v2-finance-api/snapshots.md).

## Fehler bei Excel-Downloads

Die Excel-Bücher prüfen alle Parameter und rechnen den Datensatz, bevor das erste Byte der Datei gesendet wird. `403` und `422` kommen deshalb immer als normale JSON-Antwort. Bricht die Verbindung während der Rohdaten ab, ist die Datei unvollständig, obwohl der Status `200` war. Eine solche Datei lässt sich nicht öffnen, lade sie erneut.

Lässt sich die Datei auf dem Server nicht schreiben, antwortet die API mit `500` und dem Typ `ANALYTICS_FINANCE__WORKBOOK_WRITE_FAILED`. Lade sie dann erneut herunter.