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

# Maintenance and outages

> How your system must operate when Jenzy stops the API.

Jenzy can stop the `/v1` API. The stop is **maintenance** or an **outage**.

* A **maintenance** is work that Jenzy plans.
* An **outage** is a problem that Jenzy examines.

The two stops use the same rules for money and for a request that you send
again. They use different words for your users.

## What operates during a stop

| Item                                        | During a stop                                            |
| ------------------------------------------- | -------------------------------------------------------- |
| `GET /ping`                                 | Operates                                                 |
| All other `/v1` routes                      | Give HTTP 503                                            |
| Payouts that Jenzy accepted before the stop | Stay in `held`. They do not fail. They do not move money |
| Webhooks for payouts that already completed | Continue                                                 |

Jenzy does not try accepted payouts again until the API operates.

## How you know

Send `GET /ping`. Read the `status` field.

| `status`      | Meaning                                    |
| ------------- | ------------------------------------------ |
| `live`        | The API operates                           |
| `maintenance` | Jenzy stopped the API for planned work     |
| `outage`      | Jenzy stopped the API because of a problem |

Sandbox and production are different host names
(`api.sandbox.jenzy.com` and `api.jenzy.com`). The host name is not a field
in the ping response.

If `status` is `maintenance` or `outage`, do not send other `/v1` requests.

If you send other `/v1` requests during a stop, you get HTTP 503:

| Ping `status` | Error `code`          |
| ------------- | --------------------- |
| `maintenance` | `service_maintenance` |
| `outage`      | `service_incident`    |

Use the `code` field to select the action. Do not use the `message` field. Do not use the HTTP reason text.

`GET /ping` with a bad key gives HTTP 401. This lets you see the difference
between a stop and a bad key.

There is no `Retry-After` header. Jenzy does not tell you when the API will operate again. A person at Jenzy starts the API again.

## Procedure

Do these steps in this sequence.

<Steps>
  <Step title="Find the stop">
    Send `GET /ping` when one of these happens:

    * You get HTTP 503 with `service_maintenance` or `service_incident`.
    * You start your system.
    * A create request does not complete.

    ```bash theme={null}
    curl https://api.jenzy.com/v1/ping \
      -H "Authorization: Bearer $JENZY_API_KEY"
    ```

    ```json theme={null}
    { "org": "Acme Remittances Ltd", "key_prefix": "jz_live_AbC123Xy", "status": "maintenance" }
    ```
  </Step>

  <Step title="Stop new creates">
    Do not send `POST /payouts/bank`.
    Do not send `POST /payouts/momo`.
    Do not send `POST /collections/simulate`.
    Do not send `POST /fees/quote`.

    Keep the work in your system until `GET /ping` shows `"status": "live"`.
  </Step>

  <Step title="Wait. Then send ping again">
    Send `GET /ping` again. Increase the wait after each try:

    1. Wait 30 seconds.
    2. Wait 1 minute.
    3. Wait 2 minutes.
    4. Wait 5 minutes.
    5. Then wait 5 minutes between each try.

    Do not send more than one ping in each wait.
    Do not send create requests while you wait.
  </Step>

  <Step title="Send the create again">
    When `status` is `live`:

    * Use the **same** `Idempotency-Key`.
    * Use the **same** request body.
    * Send the create again.

    A stop does not record an `Idempotency-Key`. The same key does not cause a `conflict`.

    Do not make a new `Idempotency-Key` for the same payout. A new key can cause a second payout.
  </Step>

  <Step title="Read your payouts">
    Send `GET /payouts`. Compare the list with your records.

    Payouts that Jenzy accepted before the stop continue when the API operates. You do not send those payouts again.
  </Step>
</Steps>

## Text for your users

If `status` is `maintenance`, use this text:

> We stopped payouts for planned work. Nothing is wrong with your money. Try again when the work is complete.

If `status` is `outage`, use this text:

> We stopped payouts while we examine a problem. Your balance is safe. Payouts that we already accepted are safe. We do not try those payouts again until the API operates.

Do not tell your users that a payout failed. A stop is not a failure.

## Money during a stop

Payouts that Jenzy accepted before the stop:

* Stay in `held`.
* Do not fail.
* Do not move money.
* Continue when the API operates again.

Webhooks for payouts that already completed continue during the stop:

* `payout.succeeded`
* `payout.failed`
* `payout.reversed`

You cannot send `GET /payouts` or `GET /balance` during the stop. Use the webhooks that you already received. Use your records.

When the API operates again, send `GET /payouts` to find the state of each payout.

See [Payouts](/payouts) and [Webhooks](/webhooks).

## What you must not do

* Do not make a new API key because of a stop.
* Do not make a new `Idempotency-Key` for the same payout.
* Do not send create requests in a loop.
* Do not treat `service_incident` or `service_maintenance` as `internal_error`.
* Do not treat a stop as a failed payout.
* Do not wait for a `Retry-After` header. That header is not on these responses.

## Related

* [Errors](/errors#when-jenzy-pauses-the-api) — the two pause codes
* [Payouts](/payouts#idempotency) — how an `Idempotency-Key` operates