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

# SERVICE_UNAVAILABLE

> A dependency the request needs is temporarily unavailable, so the request was rejected with HTTP 503.

## What this error means

`SERVICE_UNAVAILABLE` is returned with HTTP status **503** when a dependency
the request needs is temporarily unavailable: a brief database connectivity
blip, load shedding while the platform protects core paths under heavy load,
or a required database object that is not ready yet for your organization.
The request was not processed; retrying after a short pause is expected and
safe.

Every response for this error carries this page's address in `meta.docs_url`:

```json theme={null}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Database temporarily unavailable — please retry shortly.",
    "status": 503
  },
  "meta": {
    "request_id": "req_01J9ZKQ3V8",
    "docs_url": "https://docs.orbit.devotel.io/errors/SERVICE_UNAVAILABLE"
  }
}
```

## Cause

| State | What is happening |
| - | - |
| A brief database connectivity blip | The connection could not be served at that instant; a retry a moment later usually succeeds |
| Platform load shedding | Under sustained overload Orbit sheds excess load so core sending paths stay healthy |
| A required object not ready for your organization | Provisioning or maintenance is still converging for a resource your request touches |

## How to fix it

1. **Retry with backoff.** This is a transient fault: wait a second or two and
   reissue the request, doubling the wait between attempts. Honor a
   `Retry-After` header when one is present.
2. **Do not retry at full speed.** An immediate retry loop converts one
   shedding event into a self-inflicted rate-limit problem on top of it.
3. **Check the status page for sustained windows.** If 503s continue for more
   than a few minutes, [status.orbit.devotel.io](https://status.orbit.devotel.io)
   shows whether the platform is in a declared incident.
4. **Include `meta.request_id` if you open a ticket.** It lets support pull the
   exact request from logs.

## Related

* [Error Code Reference](https://docs.orbit.devotel.io/reference/error-codes.md#from-a-code-to-a-runbook) —
  `SERVICE_UNAVAILABLE` sits in the transient retry class.
* [Platform load shedding runbook](https://docs.orbit.devotel.io/troubleshooting/platform-load-shed-503.md) —
  what 503s mean during a shedding event and how clients should behave.
* [Error Handling Examples](https://docs.orbit.devotel.io/guides/error-handling-examples.md) — response-envelope
  handling patterns in code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.