Errors

The Joulo API uses standard HTTP status codes to indicate the success or failure of a request.

Error response format

Error responses return a JSON body with an error field:

{
  "error": "Missing or invalid API token"
}

When an OAuth2 token lacks the required scope, the response includes the missing scope:

{
  "error": "Insufficient scope",
  "required_scope": "sessions:read"
}

Status	Description	How to handle
`401`	Missing or invalid API token.	Check that your `Authorization` header is formatted as `Bearer YOUR_TOKEN`, or that the `token` query parameter is correct.
`403`	Token is valid but lacks the required scope.	Ensure your OAuth2 token was granted the scope listed in `required_scope`. Legacy API tokens have full access and never receive `403`.
`404`	The requested path does not exist.	Check the endpoint path. Available endpoints: `/chargers`, `/sessions`, `/energy`.
`405`	HTTP method not allowed.	The API only supports `GET` requests.
`429`	Rate limit exceeded.	Back off and retry after the period indicated in the `Retry-After` header.
`500`	Unexpected server error.	Retry with exponential backoff. If the issue persists, contact [email protected].

{
  "error": "Missing or invalid API token"
}

{
  "error": "Insufficient scope",
  "required_scope": "chargers:read"
}

{
  "error": "Not found. Available endpoints: /chargers, /sessions, /energy"
}

{
  "error": "Method not allowed"
}