Errors and problems

Ampere uses standard HTTP status codes. Many failure responses also include a machine-readable code and a human-readable message so clients can branch safely.

HTTP status map

Status	Meaning for partners
`400`	Invalid path/query/body (bad UUID, invalid date, validation rule failed)
`401`	Missing, expired, revoked, or otherwise invalid authentication
`403`	Authenticated, but permission or resource scope denies the call
`404`	Resource not found in the caller’s accessible context
`409`	Request conflicts with current state
`429`	Too many requests; back off and retry
`5xx`	Temporary platform failure; retry with backoff

Domain-specific codes (group membership)

Pool membership mutations return stable codes partners can key on:

Code	HTTP	When
`GROUP_NOT_MANAGEABLE`	403	Target group is not a writable curtailment pool
`GROUP_ACCESS_DENIED`	403	Caller has no access to the target group
`ADDRESS_ACCESS_DENIED`	403	Address is not owned via an accessible partner group
`MEMBERSHIP_NOT_FOUND`	404	DELETE: no active membership to remove
`ADDRESS_ALREADY_IN_CURTAILMENT_POOL`	409	Address is already active in a different curtailment pool
`GROUP_NOT_FOUND`	404	Unknown group
`ADDRESS_NOT_FOUND`	404	Unknown address

Common failure patterns

Authentication

Missing Authorization header → 401
Expired access token → 401 (refresh, then retry)
Invalid refresh token → 401 (re-login required)

Authorization

Valid token without the required permission → 403
Valid token outside assigned groups → 403

Validation

Non-UUID path parameters → 400
Mutually exclusive schedule fields provided together → 400
Missing required date range → 400

State conflicts

Adding an address that already sits in another curtailment pool → 409
Idempotent re-add of an already-active membership → success with action: "unchanged" (not an error)

Updated about 2 months ago

Did this page help you?