Dependency Unavailable

Reference · Errors

dependency_unavailable503

Infrastructure · Affects all endpoints

A required downstream service is temporarily unavailable. Retry shortly, or contact support if it persists.

What this means

The request was valid, but a service we depend on (geocoding, email, AI model configuration, or similar) failed before we could finish. This is not a problem in your payload. The HTTP status is 503 so retry logic can treat it as retriable.

When you'll see this

• A downstream dependency timed out or returned an error, and no more specific code (such as geocode_unavailable or email_delivery_failed) applied.
• An AI model required for the requested horizon is not configured.
• A required external service was unreachable at request time.

Learn more about how this works

Typed dependency failures map to HTTP 503 with dependency_unavailable unless a subclass overrides to a more specific code. Unlike internal_error (HTTP 500, an unhandled platform bug), this code means a known downstream outage. Every 503 of this kind is reported to our on-call team via Sentry.

Example response

{
  "success": false,
  "error": "dependency_unavailable",
  "message": "A required downstream service is temporarily unavailable. Please try again shortly.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/dependency_unavailable/",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Retry the same request once after 1-2 seconds. Most of these responses are transient.
2. If it fails again, save the request_id and email [email protected].
3. If many requests fail, check status.asterwise.com for an active incident.

PRODUCTION ENGINEER

Recovery pattern

Treat 503 dependency_unavailable as retriable with a single retry, then surface the request_id. Do not retry-loop.

Python:

Production handler

Python

import httpx
import logging
import time

logger = logging.getLogger(__name__)

def call_asterwise(url, headers, payload):
    for attempt in (1, 2):
        response = httpx.post(url, headers=headers, json=payload, timeout=30)
        if response.status_code == 503:
            body = response.json()
            if body.get("error") == "dependency_unavailable":
                if attempt == 1:
                    time.sleep(1)
                    continue
                logger.error(
                    "Asterwise dependency_unavailable after retry",
                    extra={"request_id": body.get("request_id")},
                )
                raise RuntimeError(f"Asterwise failure: {body.get('request_id')}")
        return response.json()

TypeScript

async function callAsterwise(url: string, headers: HeadersInit, payload: unknown) {
  for (const attempt of [1, 2]) {
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(payload),
    });
    if (response.status === 503) {
      const body = await response.json();
      if (body.error === "dependency_unavailable") {
        if (attempt === 1) {
          await new Promise((r) => setTimeout(r, 1000));
          continue;
        }
        console.error("Asterwise dependency_unavailable", {
          request_id: body.request_id,
        });
        throw new Error(`Asterwise failure: ${body.request_id}`);
      }
    }
    return response.json();
  }
}

Avoid this error by

• You cannot prevent downstream outages. Handle 503 with one retry, then report.
• Prefer lat/lon/timezone over location names so geocoding is not on the hot path.
• Log request_id on every error response so support can trace the dependency that failed.