Skip to content
aerandil.com
GitHub

Whether the card rail can be reached, and what is queued for it

GET
/v1/payments/rail/health
curl --request GET \
  --url https://api.aerandil.com/v1/payments/rail/health \
  --header 'Authorization: Bearer <token>'

The card rail’s reading — asks the processor nothing: rail is up (the last request was answered), down (it was not, since down_since: a transport failure, a 5xx or a 429 — failure says which kind, as this kernel last heard it) or unknown (nothing asked yet). Since 2026-10-21 rail, down_since, since and seen_by are every replica’s shared reading — each kernel publishes the transitions it hears — so two replicas answer the same banner; last_success_at, last_failure_at and failure stay this kernel’s own. A 401 (the platform’s key refused) moves the reading neither up nor down. With the open queue at the house (property_id, else the desk’s own house, else the tenant): the instructions still to be taken when the rail is back (queued, by kind, the oldest’s time) and those given up on in the last week (abandoned). Counts are cached for a few seconds. 501 unless AERANDIL_STRIPE_ENABLED=1.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
property_id
string format: uuid

The house whose queue is counted.

Responses

Section titled “Responses”

200

Section titled “200”

The rail’s health and the open queue.

Media typeapplication/json
object
abandoned
required
integer
down_since
string | null format: date-time
failure
string | null
Allowed values: unreachable timeout server_error rate_limited
last_failure_at
string | null format: date-time
last_success_at
string | null format: date-time
more
boolean
oldest_queued_at
string | null format: date-time
property_id
string | null format: uuid
queued
required
integer
queued_by_kind
object
capture
integer
charge_off_session
integer
refund
integer
top_up
integer
void
integer
rail
required
string
Allowed values: up down unknown
seen_by
string | null
since
string | null format: date-time
Example
{
  "failure": "unreachable",
  "rail": "up"
}

Headers

Section titled “Headers”
Cache-Control
string

Always no-store. Object and link state is live data and is never cacheable.

403

Section titled “403”

The bearer authenticated but does not hold the scope this operation requires.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

501

Section titled “501”

No card rail is configured on this deployment.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}