Billing Service Unavailable

billing-service-unavailable · 503

The API couldn't reach the billing service, or lacked an exchange rate it needed, so it changed nothing.

When billing can't be reached, the text in brackets at the end of detail says what failed. Billing is asked live when the plan changes, and the first time an organization's billing state is read. For a missing rate, detail names the currency.

This type adds no members to the ones every error carries.

Common causes

  • The billing service was down, slow or answered with an error at that moment.
  • This deployment's link to billing isn't set up, and the text in brackets says so.
  • Billing had no exchange rate for the currency at that moment, or the invoice being read was issued without one.

How to fix the call

  • Retry after a short wait: nothing changed, so the same call is safe to send again.
  • If it keeps failing, tell the user, quoting detail.
  • If detail says the invoice was issued without an exchange rate, don't retry: the answer won't change, so tell the user, quoting detail.

Example response

json
{
  "type": "billing-service-unavailable",
  "title": "Billing Service Unavailable",
  "detail": "The billing service could not be reached, so this account's billing state is unknown. Nothing has changed; try again shortly. (billing answered 502)",
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/billing/account/plan",
  "method": "PUT",
  "instance": "PUT /v1/billing/account/plan",
  "status": 503,
  "docs": "https://ghaym.me/docs/errors/billing-service-unavailable"
}