> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyparrow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Status

> Check whether Hyparrow is operating normally, from your own code, without an API key.

## Overview

`GET /status` reports the current operational state of the Hyparrow API and the components behind
it. It is **public**: no API key, no secret, no signature. Use it to drive a status widget in your
own dashboard, to decide whether a failed call is your problem or ours, or to gate a retry loop.

<Note>
  **Base URL:** `https://api.hyparrow.cloud/api/v1`

  The sandbox reports its own state separately at `https://sandbox.hyparrow.cloud/api/v1/status`.
  A healthy sandbox says nothing about live, and the reverse.
</Note>

## Request

```bash theme={null}
curl https://api.hyparrow.cloud/api/v1/status
```

No parameters, no headers, no body.

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "state": "operational",
    "components": [
      { "component": "api", "state": "operational" },
      { "component": "database", "state": "operational" },
      { "component": "cache", "state": "operational" }
    ],
    "checkedAt": "2026-09-05T09:41:12Z"
  }
}
```

| Field                         | Type   | Description                                                                 |
| ----------------------------- | ------ | --------------------------------------------------------------------------- |
| `data.state`                  | string | The overall state. One of `operational`, `degraded`, `down`.                |
| `data.components`             | array  | One entry per component, in a stable order.                                 |
| `data.components[].component` | string | Component name: `api`, `database` or `cache`.                               |
| `data.components[].state`     | string | That component's state, from the same three values.                         |
| `data.checkedAt`              | string | RFC 3339 UTC timestamp of when the reading was taken. Up to 15 seconds old. |

### States

| State         | Meaning                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `operational` | Working normally.                                                                                                                              |
| `degraded`    | Serving requests, but something behind the API is impaired. Expect slower responses or reduced non-essential function. Payments still process. |
| `down`        | Not able to serve requests reliably. Retry later rather than treating failures as declines.                                                    |

The three state values are the whole vocabulary. It is safe to switch on the string, and safe to
treat any value you do not recognise as `degraded`.

## Behaviour to rely on

<Steps>
  <Step title="The HTTP status is always 200">
    Even while reporting `down`. The response code tells you the status was served; the state is in
    the body. Read `data.state`, not the status code.
  </Step>

  <Step title="The reading is refreshed every 15 seconds">
    `checkedAt` tells you how fresh it is, and the response carries
    `Cache-Control: public, max-age=15`. Polling faster than that returns the same snapshot, so
    once every 30 to 60 seconds is a sensible interval.
  </Step>

  <Step title="The component list is stable">
    The same three components are always present, in the same order, whatever the state. New
    components may be appended in future; nothing is removed or renamed.
  </Step>
</Steps>

<Warning>
  This endpoint reports Hyparrow's own availability. It says nothing about a specific transaction,
  and nothing about the banks, card schemes or biller networks a given payment travels through.
  For the outcome of one payment, use the transaction or checkout status endpoints.
</Warning>

## Suggested use

```js theme={null}
const res = await fetch("https://api.hyparrow.cloud/api/v1/status");
const { data } = await res.json();

switch (data.state) {
  case "operational":
    break;
  case "degraded":
    showBanner("Payments are running slower than usual.");
    break;
  case "down":
    showBanner("Payments are temporarily unavailable. Please try again shortly.");
    break;
}
```

A failed API call plus a `down` from this endpoint means waiting is the right response. A failed
API call while this endpoint reports `operational` means the failure is specific to that request:
check the error body and your Developer logs.