unavailable

What it means

The OneLifeVibe Platform API returns HTTP status 503, Service Unavailable, with error code unavailable when the platform is temporarily misconfigured. Your request may be well formed and your credentials may be valid, but the endpoint cannot complete its work because something it depends on is missing from the deployment.

The response body follows the standard error shape: an error object with code, message and hint. A typical message is: The platform database is not configured on this deployment. The code field is stable. Match on unavailable and never on the message text, because the message can change.

Use this code to identify a deployment configuration problem. The related codes internal_error and world_unreachable are separate conditions, so branch on the exact code value in your error handling.

Why you are seeing it

An endpoint returns unavailable when a dependency that endpoint needs is not configured on this deployment. The named examples are the database and a gateway credential. If the database is not configured, endpoints that need it cannot run. If a gateway credential is missing, endpoints that need that gateway cannot run.

This is a deployment-level condition, not a per-request validation failure. Changing your payload or retrying with different parameters will not clear it. The useful signal is GET /api/platform/v1/health, which shows which dependencies are configured.

How to fix it

Retry later. The deployment may be corrected without any change on your side. If the error lasts, write to support@onelifevibe.com and include the endpoint you called, when the request failed, and the code, message and hint from the response.

Before you contact support, call GET /api/platform/v1/health. It shows which dependencies are configured, so you can confirm whether the database or a gateway credential is the missing piece. Keep the 503 and the code in your logs rather than collapsing it into a generic failure.

Handling it in code

Read the error body and switch on error.code. Treat unavailable as retryable but bounded: wait, retry with backoff and jitter, and stop after a sensible number of attempts. Log the HTTP status, code, message, hint and the endpoint. Do not retry in a tight loop and do not branch on message text.

When your retries are exhausted, return a clear state to the caller or park the job for later. Keep unavailable distinct from internal_error and world_unreachable in your error mapping so your dashboards show the right cause.

A health check before a batch job is a practical guard: GET /api/platform/v1/health shows which dependencies are configured, so you can delay work instead of collecting 503 responses.