API-Dokumentation

API-Fehler

Jede Fehlerantwort der API trägt ein type-Feld, das auf einen der Abschnitte unten zeigt. Der Wortlaut in einer Antwort ist immer Englisch - Protokoll wird nicht lokalisiert.

Aufbau einer Fehlerantwort

Fehler folgen RFC 9457 und werden als application/problem+json ausgeliefert. type verweist auf die Erklärung, title ist ein kurzer englischer Name, status wiederholt den HTTP-Statuscode, detail beschreibt den konkreten Fall und instance ist der Pfad, auf dem der Fehler entstanden ist.

json

{
  "type": "https://spotforecast.eu/problems/unknown-zone",
  "title": "Unknown bidding zone",
  "status": 404,
  "detail": "Zone XX is not available",
  "instance": "/v1/forecast"
}

`invalid-request`

HTTP 400Invalid request

Die Anfrage enthält einen Parameter, den die API nicht annimmt. Es kann ein Pflichtparameter fehlen, oder ein Parameter hat einen unbekannten Wert oder das falsche Format. Das Feld detail nennt den Parameter; seine erlaubten Werte stehen beim Endpunkt in der Dokumentation.

`no-route`

HTTP 404No such endpoint

Diese Adresse gehört nicht zur API. Prüfen Sie den Pfad einschließlich des /v1 am Anfang; die vollständige Liste der Endpunkte steht in openapi.json.

`unknown-zone`

HTTP 404Unknown bidding zone

Diesen Zonencode kennen wir nicht. Nehmen Sie die Codes aus /v1/zones und übernehmen Sie sie genau, mit Großbuchstaben und Bindestrichen (DK1, IT-NORD).

`no-forecast`

HTTP 404No forecast for this zone

Die Zone gibt es, wir führen zu ihr aber nur abgerechnete Marktpreise und keine Prognose. Verwenden Sie dafür /v1/prices; welche Zonen eine Prognose haben, sagt das Feld has_forecast in /v1/zones.

`no-vintage`

HTTP 404No forecast of that vintage

Zum angefragten Zeitpunkt as_of oder davor wurde keine Prognose veröffentlicht. Ein erneuter Versuch hilft nicht - fragen Sie ein neueres as_of an.

`missing-credentials`

HTTP 401Missing API key

Die Anfrage enthält keinen API-Schlüssel. Senden Sie ihn im Header Authorization: Bearer <Schlüssel> oder X-API-Key: <Schlüssel>.

`invalid-credentials`

HTTP 401Invalid API key

Diesen Schlüssel kennen wir nicht, oder er wurde widerrufen. Prüfen Sie, ob Sie ihn vollständig kopiert haben; einen neuen erstellen Sie in Ihrem Konto.

`plan-limit`

HTTP 403Not available on your plan

Die Anfrage reicht weiter, als Ihr Tarif erlaubt. Was Ihr Tarif abdeckt, sehen Sie in Ihrem Konto.

`rate-limit`

HTTP 429Rate limit exceeded

Das Tageskontingent an Anfragen ist aufgebraucht. Der Header Retry-After nennt die Wartezeit in Sekunden, X-RateLimit-Remaining die verbleibenden Anfragen; das Limit gilt pro Konto und nicht pro Schlüssel, mehr Schlüssel vervielfachen es also nicht.

`no-data`

HTTP 503No data available

Für diese Zone veröffentlichen wir Prognosen, es ist aber noch kein Modelllauf eingetroffen. Hier lohnt sich ein erneuter Versuch - anders als bei einem 404 ist das ein vorübergehender Zustand.

`internal`

HTTP 500Internal server error

Ein Fehler auf unserer Seite. Versuchen Sie die Anfrage erneut, und wenn das Problem bleibt, melden Sie sich bei uns mit der Uhrzeit der Anfrage und dem Feld instance aus der Antwort.