Errors and limits

Costs apply to Growbud Cloud only. Calls to your own Edge Server are free. They use no API balance and have no X-API-Balance-USD header.

Sensors, thresholds and account

An error is text, not JSON. The 405 is JSON: {"error": "..."}.

Status	When
400	A parameter is not valid. The text tells which.
401	There is no token, or the token is not valid.
403	API access is off in your profile. Or you have no API credits: `API credits exhausted. Please recharge your account.` Or none of the sensors you asked for are on your account.
405	`PUT /api/thresholds` or `PUT /api/thresholds/batch`. You cannot change thresholds with this API. Change them in the Growbud app or on an Edge Server.
429	About 60 requests in one minute. Wait, then send again.
500	A server error. Send the request again.

Costs (Growbud Cloud only)

These calls go to Growbud Cloud at https://growbud-api-a2a9c.web.app. Each request that passes authentication is charged from your USD balance, also if it then fails. The X-API-Balance-USD header gives the balance after the request, to the nearest cent.

Endpoint	Cost (USD)
`/api/list-sensors`	$0.0001
`/api/thresholds`	$0.0005
`/api/latest`	$0.0005
`/api/query`	$0.0001 + $0.00001 for each hour of `duration` ($0.0217 maximum)
`/api/balance`	No charge

The same reads on your Edge Server are free.

History

Sensor	History from `/api/query`
Growbud sensor	2160 hours (90 days) maximum, as 15-minute averages
LoRaWAN sensor with a label serial	2160 hours maximum, as 15-minute averages
LoRaWAN sensor with no label serial	168 hours (7 days) maximum, each reading

metadata.historyStart gives the time of the first data for a LoRaWAN sensor. If duration starts before that time, the data starts at historyStart and metadata.clamped is true. pressure_hpa is kept 7 days.

Outlets, Controllers and the Write API

An error is JSON:

{ "error": { "code": "permission_denied", "message": "This token may read only. Control needs a token with the control scope." } }

Status	Code	When
400	`invalid_argument`	A parameter or a body field is not valid.
401	`unauthenticated`	There is no token. Or the token is not from this Edge Server, is revoked or has expired.
403	`permission_denied`	The token has no `control` scope.
404	`not_found`	The outlet, Controller or command does not exist, or is in a different organization.
405	`invalid_argument`	The path is correct, but the method is not.
409	`managed_elsewhere`	The Edge Server is on standby. Make the change in Growbud Cloud.
409	`failed_precondition`	You cannot do this now. For example, the Controller output has no load type.
429	`rate_limited`	More than 30 requests in one minute with no valid token. Wait one minute.
500	`internal`	A server error. Send the request again.
502, 503	`unavailable`	The Edge Server could not complete the request. Nothing changed. Send it again.

Wait for a result

Some calls take wait, 0 to 30 seconds. The answer comes when the result is final, or when the time ends. A value more than 30 gives 400. These calls take wait:

Outlets: POST .../switch and GET .../commands/{commandId}.
Controllers: POST .../outputs/{ch}/switch and GET .../commands/{commandId}.

Retention

Data	Kept
Power readings	35 days
Commands	30 days
Record of control calls	365 days