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

# Troubleshoot 503 UNDER_PRESSURE — when the platform sheds load

> UNDER_PRESSURE is the platform's ELU-based load-shed response. It answers a retryable 503 with a Retry-After header the moment the process event loop is saturated, instead of hanging until the edge gives up. This page explains what it means, how to distinguish it from a systemic SERVICE_UNAVAILABLE, what retry posture to use, and when to contact support.

# Troubleshoot `503 UNDER_PRESSURE` — when the platform sheds load

`UNDER_PRESSURE` is the platform's **load-shed** response: the server answers
a fast, retryable `503` with a `Retry-After` header the moment its event loop
is saturated, instead of letting requests queue behind a stuck loop until
they hang past the edge timeout. It names a **transient** shed, not a
systemic outage — the server is healthy enough to answer immediately.

This page covers the script-shaped 503 envelope that carries
`error.code = UNDER_PRESSURE`. When a request lands on the `/health` or
`/ready` probes, the shed is bypassed; this page covers every other route.

## What the UNDER\_PRESSURE code means

Orbit's API samples two pressure signals on every request: event-loop delay
(mean, via `perf_hooks.monitorEventLoopDelay`) and event-loop utilization
(delta ELU). When the loop is wedged — delay is high and ELU is near-saturated,
corroborated across consecutive sample windows — the gate answers `503`
immediately instead of letting the request queue behind the loop until it
times out silently. The code `UNDER_PRESSURE` names this transient shed
explicitly and distinguishes it from the general `SERVICE_UNAVAILABLE` code
saved for systemic dependency failures (a pgbouncer blip, a slow migration, a
provider outage).

The shed gives up the response in a few milliseconds with a `Retry-After`
header, so it buys relief instead of amplifying the pressure. The gate also
leaves the `/health`, `/ready`, CORS preflight (`OPTIONS`), and a per-route
exempt list untouched, so a fleet-wide pressure blip cannot disable the
platform's own probes or break browser preflight requests — the two
self-inflicted outage classes the shed exists to avoid.

## Distinguish UNDER\_PRESSURE from SERVICE\_UNAVAILABLE

Both are `503`. Use this table to decide the retry posture and whether it is
a shed or a systemic fault.

| Signal               | `UNDER_PRESSURE`                                                 | `SERVICE_UNAVAILABLE`                                                                                                            |
| -------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| HTTP status          | 503                                                              | 503                                                                                                                              |
| `error.code`         | `UNDER_PRESSURE`                                                 | `SERVICE_UNAVAILABLE`                                                                                                            |
| `Retry-After` header | Present (seconds)                                                | Usually absent; check `details.retry_after` inside the error if the handler set one                                              |
| Surface              | The platform event loop is saturated                             | A named dependency (database, wallet provider) is down or slow                                                                   |
| Retry posture        | Retry after `Retry-After` seconds; the request is safe to replay | Idempotent read? Safe to retry after the `Retry-After` / `retry_after` hint. Mutating write? Retry only with an idempotency key. |

On a typical healthy integration, `UNDER_PRESSURE` almost never appears. When
it does, it is usually paired with the platform's load-shedding itself — a
deploy burst, a regional pod burst, or a slow upstream dependency tripping
the loop on that one route. The request id is still stamped into the
`meta.request_id` so support can trace the shed.

<Note>
  The `UNDER_PRESSURE` code was introduced 2026-09-24 on the load-shed gate.
  Before then the same behaviour emitted the generic `SERVICE_UNAVAILABLE`
  code — integrators could not tell a transient shed from a systemic fault.
  Treat any observed `UNDER_PRESSURE` response as the transient-shed signal
  this page describes. The general 503 envelope contract is
  [Error response format](/reference/error-codes#error-response-format).
</Note>

## Retry posture

`UNDER_PRESSURE` is **retryable as-is**. The right posture is:

1. Read `Retry-After` from the header. When it is present (it always is on
   this gate), sleep that many seconds before the retry. When it is absent,
   fall back to exponential backoff (`2 ** attempt` seconds, capped).
2. Retry only the request that was shed. Do not loop over the full batch —
   that amplifies the load the shed exists to relieve.
3. Idempotency keys benefit every retry. `UNDER_PRESSURE` itself is safe to
   replay, but when you retry a mutating write (a `POST /messages`, a
   `POST /billing/top-up`), send the same idempotency key you used the first
   time. The idempotency window replays the original response on a duplicate
   instead of running the write again. See
   [Idempotency and safe retries](/concepts/idempotency-and-safe-retries).

The [Error codes reference](/reference/error-codes) page's language samples
show the retry loop in Node.js, Python, and Go — the same pattern that
honours `Retry-After` when present and exponential backoff otherwise.

## Escalation — when to contact support

The shed is transient. Contact support only when one of these holds:

* The same endpoint returns `UNDER_PRESSURE` consistently for more than a
  few minutes, or returns it on every retry inside one deploy window.
* You see `UNDER_PRESSURE` on a route that should have been idle, or you can
  reproduce the shed from a single request.

Open a ticket with the `meta.request_id` from one of the responses and a
UTC timestamp. Support can localize the shed in the platform's
`api.load_shed` log and confirm the `event_loop_delay_ms` /
`event_loop_utilization` the gate recorded when it answered.

<Note>
  The `Retry-After` value is bounded (the gate only hints at a short wait).
  If your integration retries with jittered exponential backoff for hours,
  that is a systemic issue — contact support and include the request id.
</Note>