Limits, errors and support

How many requests you can make, how to build an integration that holds up over time, what the errors mean and whom to contact.

Limits

2 000 requests per day and 60 per minute per client; higher limits under a dedicated agreement.

A bulk call counts as one request, whatever the number of plants in the page. A bulk page holds at most 100 plants.

Best practice

• Cache the token for its full hour; do not request one per call.
• Use bulk endpoints for periodic reads of more than one plant.
• Paginate with the cursor: pass pagination.next_cursor back as cursor until has_more is false. Treat the cursor as opaque.
• Back off on 429 and 503: wait and retry with exponential backoff (for example 1 s, 2 s, 4 s, up to a minute), adding a random jitter.
• 404 means not visible: the plant does not exist or is not linked to your organization. The API does not distinguish the two.
• Tolerate new fields: ignore fields you do not know; they may be added within /v1.
• null is a value: handle null power, state of charge and energy fields.

Errors

Every API error returns the same JSON envelope:

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

Errors of the token endpoint follow the OAuth 2.0 format instead ({"error": "invalid_client"}).

Code	HTTP	Meaning	Action
INVALID_TOKEN	401	missing, malformed or invalid token	obtain a new token
TOKEN_EXPIRED	401	token expired	obtain a new token
INVALID_AUDIENCE	401	token not issued for this API	use your API client's credentials
AUTHENTICATION_FAILED	401	authentication failed	obtain a new token
SCOPE_REQUIRED	403	your client lacks the required scope	contact zeroCO2
PLANT_NOT_FOUND	404	plant unknown or not visible to your client	check the id against GET /v1/plants
INVALID_QUERY_PARAM	400	missing or invalid parameter	fix the request; details names the parameter
RATE_LIMIT_EXCEEDED	429	request limit reached	back off and retry
SERVICE_UNAVAILABLE	503	temporary unavailability	back off and retry
JWKS_UNAVAILABLE	503	token could not be verified	back off and retry
INTERNAL_ERROR	500	unexpected error	retry once, then contact support

A 429 or 5xx may occasionally arrive without the envelope: always rely on the HTTP status code.

Versions

The API version is part of the path (/v1). Within a version, changes are backward compatible: new endpoints, new optional parameters and new response fields may be added. Incompatible changes are published under a new version (/v2), and the previous version remains available for a transition period announced in advance.

Support

Email: info@energysynt.com · Phone: +39 049 5017583

Please include the request_id of the failing call, the endpoint and the time of the request (UTC).