Skip to main content

​
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. 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.
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.

​
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.
The Error codes reference 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.
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.