Errors

Every failure returns a standard HTTP status code and a consistent body, application/problem+json (RFC 7807):

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required.",
  "reason": "auth.missing_token",
  "meta": {}
}

Field	Description
`title`	Short summary, matching the HTTP status phrase.
`status`	HTTP status code.
`detail`	Human-readable explanation, safe to show an end user.
`reason`	Stable machine-readable code. Handle errors on this, not on `title` or `detail`, which are for humans and may change.
`meta`	Extra context, such as which field failed validation. May be empty.

Status codes

Status	When it occurs
`400 Bad Request`	Invalid body or parameters. `meta` carries field-level detail (below).
`401 Unauthorized`	Authentication failed. See the `auth.*` `reason`.
`403 Forbidden`	The token lacks permission for this action.
`404 Not Found`	The resource does not exist.
`409 Conflict`	A conflict prevented the operation, e.g. an `Idempotency-Key` reused with a different body (`reason: idempotency.failure`).
`412 Precondition Failed`	A required condition was not met, e.g. the charge point is not `Available`.
`429 Too Many Requests`	Rate limit exceeded. Back off and retry.
`503 Service Unavailable`	Temporary; retry after a short delay.
`504 Gateway Timeout`	The request timed out; retry after a short delay.
`500 Internal Server Error`	Something went wrong on our side.

Retrying

503 and 504 responses carry a Retry-After header (seconds); use exponential backoff for repeated failures. An operation sent with an Idempotency-Key is safe to retry on a network error without creating a duplicate. Reusing a key with a different body returns 409 with reason: idempotency.failure: use the original result, or a new key for a distinct operation.

Validation detail

On a 400, meta pinpoints what was wrong, so you can show a precise message or fix the request in code:

"meta": {
  "violations": [
    {
      "field": "chargePointId",
      "message": "Provide chargePointId to start a session",
      "validationRule": "mutually_exclusive"
    }
  ]
}

Authentication errors

See Authentication for the full list of auth.* reason codes.