# Get balance

> Check your 23 Telecom account balance via GET /user/balance — currency, credit-block status and degraded-cache signaling with X-Sms-Gateway-Status headers.
> Source: https://docs.23telecom.co.uk/account/balance/

Instructions for LLMs: This is one page of the 23 Telecom messaging API docs
(SMS today; more channels planned). Base URL: https://restlink23telecom.com/api/v1,
auth via the X-API-Key header. Match errors on the error_code field, never on
description text. Full docs: https://docs.23telecom.co.uk/llms-full.txt · Schemas: https://docs.23telecom.co.uk/openapi.yaml

Current account balance.

`GET /api/v1/user/balance` (permission: `balance.read`)

## Request

```
GET https://restlink23telecom.com/api/v1/user/balance
Header: X-API-Key: <your key>
```
*(The web page shows this example in cURL, Node.js, Python, PHP, Ruby, Java, Go and .NET.)*

## Response

```json title="200 OK"
{
  "balance": 1250.50,
  "currency": "EUR",
  "updated": "2026.02.13 10:15:00"
}
```

When the balance is zero or negative, the response additionally contains
`"credit_blocked": true` — SMS sending is blocked until you top up.

  During onboarding this endpoint returns HTTP 200 with
  `{"status": false, "error": "Account is in setup process", …}` —
  treat it as "not ready yet", not as an error.

## Balance checks on send

Every [send request](/sms/send) is pre-checked against your balance. If it
would exceed the available funds you get `402 INSUFFICIENT_BALANCE` with the
estimated cost breakdown:

```json title="402 Payment Required"
{
  "status": false,
  "error_code": "INSUFFICIENT_BALANCE",
  "description": "Insufficient balance",
  "balance": 0.42,
  "estimated_cost": 1.07,
  "currency": "EUR",
  "total_recipients": 100,
  "billable_recipients": 98,
  "segments": 2
}
```

## Degraded state

Balance, pricing and payments are served from a background-refreshed cache.
If the cache is unavailable, the API still returns HTTP 200 but flags
degradation via response headers:

| Header | Values | Meaning |
| --- | --- | --- |
| `X-Sms-Gateway-Status` | `partial`, `unavailable` | Data quality indicator |
| `X-Sms-Gateway-Reason` | `cache_disabled`, `cache_miss_refresh_failed` | Machine-readable reason |

These headers are **absent** on healthy responses. Degraded balance responses
look like `{"balance": 0, "currency": "EUR", "unavailable": true, "reason": "…"}` —
check the `unavailable` flag before alerting on a zero balance.

## Monitoring recommendation

Poll balance once every few minutes at most (the cache refreshes on its own
cadence), alert on `credit_blocked: true`, and ignore zero-balance readings
that carry the `unavailable: true` flag.