Limits, Fehler und Support

Wie viele Requests Sie stellen können, wie Sie eine dauerhaft stabile Integration bauen, was die Fehler bedeuten und an wen Sie sich wenden.

Limits

2 000 Requests pro Tag und 60 pro Minute pro Client; höhere Limits nach gesonderter Vereinbarung.

Ein Bulk-Aufruf zählt als ein Request, unabhängig von der Anzahl der Anlagen auf der Seite. Eine Bulk-Seite umfasst höchstens 100 Anlagen.

Best Practices

• Token cachen für seine volle Stunde; keinen Token pro Aufruf anfordern.
• Bulk-Endpoints verwenden für periodische Abfragen mehrerer Anlagen.
• Paginieren mit dem Cursor: pagination.next_cursor als cursor zurückgeben, bis has_more false ist. Den Cursor als opaken Wert behandeln.
• Bei 429 und 503 zurückhalten: warten und mit exponentiellem Backoff erneut versuchen (zum Beispiel 1 s, 2 s, 4 s, bis zu einer Minute), mit zufälligem Jitter.
• 404 bedeutet nicht sichtbar: Die Anlage existiert nicht oder ist nicht mit Ihrer Organisation verknüpft. Die API unterscheidet die beiden Fälle nicht.
• Neue Felder tolerieren: Unbekannte Felder ignorieren; sie können innerhalb von /v1 hinzukommen.
• null ist ein Wert: null-Werte bei Leistung, Ladezustand und Energie behandeln.

Fehler

Jeder API-Fehler liefert dasselbe JSON-Envelope:

{
  "error": {
    "code": "PLANT_NOT_FOUND",
    "message": "Plant 7b0728a9-853c-4b31-8446-a4eb00607566 not found",
    "request_id": "req_21ee1d5946a8",
    "details": {}
  }
}

Fehler des Token-Endpoints folgen dagegen dem OAuth-2.0-Format ({"error": "invalid_client"}).

Code	HTTP	Bedeutung	Maßnahme
INVALID_TOKEN	401	Token fehlt, ist fehlerhaft oder ungültig	neuen Token anfordern
TOKEN_EXPIRED	401	Token abgelaufen	neuen Token anfordern
INVALID_AUDIENCE	401	Token nicht für diese API ausgestellt	Zugangsdaten Ihres API-Clients verwenden
AUTHENTICATION_FAILED	401	Authentifizierung fehlgeschlagen	neuen Token anfordern
SCOPE_REQUIRED	403	dem Client fehlt der erforderliche Scope	zeroCO2 kontaktieren
PLANT_NOT_FOUND	404	Anlage unbekannt oder für den Client nicht sichtbar	ID mit GET /v1/plants prüfen
INVALID_QUERY_PARAM	400	Parameter fehlt oder ist ungültig	Request korrigieren; details nennt den Parameter
RATE_LIMIT_EXCEEDED	429	Request-Limit erreicht	warten und erneut versuchen
SERVICE_UNAVAILABLE	503	vorübergehend nicht verfügbar	warten und erneut versuchen
JWKS_UNAVAILABLE	503	Token konnte nicht geprüft werden	warten und erneut versuchen
INTERNAL_ERROR	500	unerwarteter Fehler	einmal wiederholen, dann Support kontaktieren

Ein 429 oder 5xx kann gelegentlich ohne Envelope eintreffen: Verlassen Sie sich immer auf den HTTP-Statuscode.

Versionen

Die API-Version ist Teil des Pfads (/v1). Innerhalb einer Version sind Änderungen abwärtskompatibel: Neue Endpoints, neue optionale Parameter und neue Felder in Responses können hinzukommen. Inkompatible Änderungen werden unter einer neuen Version (/v2) veröffentlicht; die vorherige Version bleibt für eine vorab angekündigte Übergangszeit verfügbar.

Support

E-Mail: info@energysynt.com · Telefon: +39 049 5017583

Bitte geben Sie die request_id des fehlgeschlagenen Aufrufs, den Endpoint und den Zeitpunkt des Requests (UTC) an.