Errors, pagination and versioning

Three conventions hold for every endpoint. Learn them once and you can predict how an endpoint you have never called will behave.

Handle errors

Every error the API returns, whatever its status, has the same body:

{
  "error": "forbidden",
  "message": "you do not have permission to do this",
  "requestId": "7f1c0e2a-5b8d-4c1e-9a53-2f0d6f4b1e77"
}

• error is a stable code, usually camelCase. The refusals to change who holds what are dotted, such as permission_policy.not_grantable or binding.holder_outside_home_project. Switch on it.

• message is for people and may be reworded at any time. Never parse it.

• requestId identifies this request in Flowion's logs.

New codes can appear within /v1, so give your switch a fallback that treats an unknown code as a generic error of that HTTP status. Each endpoint's page in the API reference lists the codes it returns today.

A 500 always reads internalError with a fixed message. The cause is logged on Flowion's side, under the request id.

A 503 is one of two codes, and both carry a Retry-After header with the seconds to wait. serviceUnavailable means something Flowion needs did not answer just now; vendorUnavailable means the charger maker's own cloud (Easee or Zaptec) did not. Wait, then send the request again, with the same Idempotency-Key if it had one. Which part failed is in Flowion's logs under the requestId, so quote that to support. A 504 (timedOut) is different: the request may have been carried out, so read before you repeat a write that had no key.

Find out why a request was refused

Every request is checked against the permission policies the caller holds. A refusal comes in one of four forms, and each tells you what to look at next:

The message of a 403 is never the reason to switch on. To learn the reason for certain, ask: Explain a decision takes the member, the permission and where, and returns the decision the API made, or would make, with the reason spelled out. It needs identity.policy.explain.

See Write your first policy for an explain call from start to finish.

Policy and binding errors

Writing a policy, giving one to someone or taking one away can be refused for one of these reasons. Each is a stable error code, and the message names the statement when a document is at fault:

Giving a policy someone already holds here, or the Owner's own policy, answers 409 conflict. Everything else a policy request can be refused for is a 403 forbidden or a 404 notFound, as above.

Quote the request id

Every response, success or error, carries an x-request-id header. Quote it when you contact support, and Flowion can find the exact request.

To tie requests to your own logs, send your own x-request-id: up to 128 letters, digits, -, _, . and :. Flowion keeps it and echoes it back. Anything else is replaced with a generated id rather than refused. Browsers can read the header from another origin.

Page through lists

Every list pages with a cursor. Ask for a page with limit, then pass each page's nextCursor back as cursor until it comes back null:

curl -G "$API/projects/$PROJECT/charging-stations" \
  -d limit=100 \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "3f2a9b1c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
      "chargePointId": "garage-01"
    }
  ],
  "nextCursor": "AUx0y2Fh3kQAAAAAAAAAAAAAFMGz_w"
}

curl -G "$API/projects/$PROJECT/charging-stations" \
  -d limit=100 \
  -d cursor=AUx0y2Fh3kQAAAAAAAAAAAAAFMGz_w \
  -H "Authorization: Bearer $TOKEN"

• limit defaults to 20 and goes up to 100. A larger value is lowered to the maximum, not refused. A few endpoints have their own default and maximum; their reference page says so.

• cursor is opaque: do not build, parse or store one. It works only with the filters and limit it was issued with. Change either and start from the first page. A cursor used anywhere else answers 400 invalidCursor.

• nextCursor is null on the last page. A short page does not mean the end, so check nextCursor.

Lists have no page numbers and no totals: page and perPage answer 400 invalidRequest, like any parameter an endpoint does not take. When you need a count, use an endpoint built for it. For chargers, GET /v1/projects/{projectId}/fleet-health returns total, online, offline, faulted and neverConnected in one call.

A few short lists, such as a charger's outlets and connectors, return everything at once with data only. The reference shows which lists take cursor.

Rely on /v1

Every route lives under /v1. Within it, changes only add:

• Safe, and made without notice: a new response field, a new optional request field, a new endpoint, a new error code, a new value in a response enum, a new variant of a response union.

• Breaking, and only in a new version: removing or renaming a field, changing a field's type, or accepting less than before.

So read responses tolerantly: ignore fields you do not know, handle codes you do not recognise, and give every switch on a response enum or union a fallback. A value your code has not seen is not an error in the API.

Expect six months' notice

Something that is going away is deprecated first, and stays for at least six months before it is removed. During that time it works exactly as it did. Three signals tell you, so you can pick up whichever your integration already reads:

• In the reference. The endpoint's page carries a notice with the removal date and a link to its replacement. A deprecated field is marked the same way.

• In the API document. The operation or field is marked deprecated, with x-deprecated-since, x-sunset (the earliest removal date) and, when there is one, x-replaced-by.

• On every response. A deprecated endpoint answers with a Deprecation header, a Sunset header carrying the removal date, and, when it has a replacement, a Link header with rel="successor-version". Errors carry them too, so a client that only ever sees a failure still learns of it.

A change that cannot be made additively arrives as /v2, served beside /v1 for the whole notice period, so you move when you are ready and not on the day it ships. Removing a deprecated endpoint or field before the six months are up is refused by Flowion's own release checks.

Pin an SDK version

The SDKs are versioned as one family. Every SDK shares the same MAJOR.MINOR and each has a PATCH of its own, so every 0.3.x describes the same API, and a patch fixes one language without moving the others.

• They start at 0.x. Until Flowion declares 1.0, a change that is not backwards compatible raises MINOR, so pin to a MINOR and upgrade it deliberately.

• From 1.0 on, MINOR only adds and MAJOR is the one that can break you.

• Which number moves is computed from what changed in the API. It is never chosen by hand, so a release that breaks you cannot ship as a patch.

Next: Sending commands.