Errors

All API errors are returned as JSON with a single human-readable error field:

{ "error": "station not found" }

Status codes

Status	Meaning	What to do
200 OK	Success.	—
400 Bad Request	Malformed query parameter (bad number, bad ISO 8601 timestamp).	Fix the client.
401 Unauthorized	Token missing, expired, invalid, or client not registered.	Re-fetch the token; if persistent, contact Persium.
403 Forbidden	Your client has been disabled.	Contact Persium support.
404 Not Found	Resource does not exist or belongs to a different organisation.	Verify the UUID is yours.
500 Internal Server Error	Persium-side issue.	Retry with backoff; escalate if persistent.

401 vs 403

These look similar but mean different things.

401 is the token's fault. It's transient: re-fetching usually fixes it. Always re-fetch and retry once before giving up.

403 is your client's fault. The client is registered but disabled. Retrying will not help — contact Persium.

404 confidentiality

Persium does not distinguish between "this UUID doesn't exist" and "this UUID exists but belongs to a different organisation". Both return 404 Not Found. This is deliberate — it prevents your credentials from being used to probe for the existence of other organisations' stations.

If you get 404 for a UUID you believe belongs to you, double-check via GET /stations that the UUID is in your organisation's list.

Retries

For 5xx responses, retry up to 3 times with exponential backoff (e.g. 1s, 2s, 4s).

Do not retry 4xx — the request will not succeed without changes to the request itself (other than the 401 token-refresh case above).

Validation errors

400 Bad Request is most often a query parameter problem:

Likely cause	Example error message
Non-numeric page/per_page	strconv.Atoi: parsing "two": invalid syntax
Bad start_time/end_time format	parsing time "2026-05-01" as "2006-01-02T15:04:05Z07:00": ...
Missing path UUID	uuid is required

Use ISO 8601 with the trailing Z (or an explicit offset) and positive integers for paging.