Fehler

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.

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

{
  "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:

{
  "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.

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.

Einführung

Grundlagen

Pläne

Angebote

Finanzberichte

Provisionen

Zahlungspläne

Statuscodes

Ungültige Parameter

Finanzberichte nicht freigeschaltet

404

409

Fehler bei Excel-Downloads

​Statuscodes

​Ungültige Parameter

​Finanzberichte nicht freigeschaltet

​404

​409

​Fehler bei Excel-Downloads

Statuscodes

Ungültige Parameter

Finanzberichte nicht freigeschaltet

404

409

Fehler bei Excel-Downloads