Resource Not Found

Reference · Errors

resource_not_found404

Not Found · Affects all endpoints

The requested resource doesn't exist or isn't yet available. Verify the URL or wait if generation is in progress.

What this means

A request resolved to a known endpoint, but the specific resource being requested (by ID, slug, name, or date) doesn't exist. This is the generic 404 — when a more specific code applies (account_not_found, key_not_found, etc.), we use that instead. resource_not_found covers the cases that don't have a dedicated code: missing crystals, dream symbols, tarot cards, angel numbers, invoices, OAuth connections, and horoscopes that haven't been generated yet.

When you'll see this

• A path parameter (crystal slug, tarot card ID, angel number) doesn't match any catalogued resource.
• An invoice ID or OAuth connection ID was looked up but doesn't exist for this account.
• A horoscope for a specific period was requested but hasn't been generated yet by the scheduled job. In this case the response includes a retry_after: 300 field — wait 5 minutes and retry.
• A typo in a URL path produced a valid-looking but non-existent slug.

Learn more about how this works

resource_not_found is the fallback 404 when no more-specific code fits. Most of the time it's a static catalog miss: you asked for crystal "amethyste" (misspelled) instead of "amethyst." Sometimes it's dynamic: a horoscope for today's date might not exist yet because the generation cron hasn't run, in which case the retry_after field tells you to wait and try again.

The most common gotcha: this error doesn't distinguish "never existed" from "existed but deleted." If you have a UI that lists items and lets users click into details, expect this error if items are deleted between list and detail load. Handle it as "this item is gone" rather than "system error."

Example response

{
  "success": false,
  "error": "resource_not_found",
  "message": "The requested resource was not found at this endpoint. Verify the URL path and resource identifier.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/resource_not_found",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Check the spelling and case of any slug or ID in the URL path. Slugs are lowercase-with-hyphens.
2. If the retry_after field is present in the error body, the resource is being generated — wait that many seconds and retry.
3. For catalog endpoints (crystals, tarot cards, dream symbols, etc.), call the list endpoint (GET /v1/crystals, etc.) to see all valid IDs.

PRODUCTION ENGINEER

Recovery pattern

Read the retry_after field — it disambiguates "will exist soon" from "doesn't exist at all."

Python:

Production handler

Python

import httpx
import time

class ResourceMissingError(Exception):
    """Resource doesn't exist and won't be auto-generated."""

def fetch_resource(url, headers, max_wait=300):
    for attempt in range(2):
        response = httpx.get(url, headers=headers, timeout=15)
        if response.status_code == 404:
            body = response.json()
            if body.get("error") == "resource_not_found":
                retry_after = body.get("retry_after")
                if retry_after and attempt == 0 and retry_after <= max_wait:
                    time.sleep(retry_after)
                    continue
                raise ResourceMissingError(
                    body.get("message", "Resource not found.")
                )
        response.raise_for_status()
        return response.json()

TypeScript

class ResourceMissingError extends Error {}

async function fetchResource(
  url: string,
  headers: HeadersInit,
  maxWait = 300,
) {
  for (let attempt = 0; attempt < 2; attempt++) {
    const response = await fetch(url, { headers });
    if (response.status === 404) {
      const body = await response.clone().json();
      if (body.error === "resource_not_found") {
        const retryAfter = body.retry_after as number | undefined;
        if (retryAfter && attempt === 0 && retryAfter <= maxWait) {
          await new Promise((r) => setTimeout(r, retryAfter * 1000));
          continue;
        }
        throw new ResourceMissingError(
          body.message ?? "Resource not found.",
        );
      }
    }
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }
}

Avoid this error by

• For catalog endpoints, always call the list endpoint first to populate valid IDs. Don't construct IDs by hand.
• For horoscope endpoints, call slightly after the period boundary (a few minutes after midnight UTC for daily) so the generation cron has had time to run.
• When you delete a resource from your own UI, also remove it from any cached list state so subsequent clicks don't hit this error.
• Slugs are case-sensitive and use hyphens, not underscores. the-fool works; The_Fool doesn't.

RELATED ERRORS

account_not_found

specific 404 for accounts.

key_not_found

specific 404 for API keys.

subscription_not_found

specific 404 for subscriptions.

city_not_found

specific 404 for geocode misses.

interpretation_not_found

specific 404 for numerology interpretations.