> Documentation index: https://roxyapi.com/llms.txt. Building an integration? Read https://roxyapi.com/AGENTS.md first.

# Astrology API error codes

Every failed RoxyAPI request answers with the same three fields. Find the `code` on this page and you have the fix.

```json
{
  "error": "Card not found: the-fool-of-cups",
  "code": "not_found",
  "doc_url": "https://roxyapi.com/docs/errors#not_found"
}
```

| Field | Use it for |
|---|---|
| `error` | Reading. Plain English, and the wording can change, so never branch on it |
| `code` | Branching. A stable identifier, safe to switch on forever |
| `doc_url` | Looking it up. An absolute link to the entry on this page for that exact code |

`doc_url` is the same URL in every environment, so log it, print it in your CLI, or paste it into a bug report and whoever reads it lands on the explanation.

A `400` adds one more field, `issues`, listing every field that failed at once so you can correct the whole request in a single retry instead of one round trip per mistake. See [validation_error](#validation_error).

**Tip: Every error the API answers is JSON, on every endpoint, including `404`. Parse the body before you decide what went wrong, and branch on `code`, never on the status alone.**

## Every code at a glance

| Status | Code | When |
|--------|------|------|
| 400 | [`validation_error`](https://roxyapi.com/docs/errors#validation_error) | A field is missing or invalid. The body lists every failing field at once in issues, each with its path and the expected shape. |
| 400 | [`bad_request`](https://roxyapi.com/docs/errors#bad_request) | The request was rejected as a whole, for example a body that is not valid JSON or a date range that ends before it starts. |
| 400 | [`date_out_of_range`](https://roxyapi.com/docs/errors#date_out_of_range) | A date lies outside the span the planetary positions are served for. The error names the supported dates. |
| 400 | [`invalid_branding`](https://roxyapi.com/docs/errors#invalid_branding) | The report branding cannot be used, for example a logo that is not a PNG, JPEG, WebP or SVG image. |
| 400 | [`logo_fetch_failed`](https://roxyapi.com/docs/errors#logo_fetch_failed) | The report logo could not be fetched: it must be an HTTPS URL on a public host that answers within the size limit. |
| 400 | [`unsupported_character`](https://roxyapi.com/docs/errors#unsupported_character) | The report text holds a character no report font draws. The error names it: remove or replace it. |
| 401 | [`api_key_required`](https://roxyapi.com/docs/errors#api_key_required) | No API key was sent. |
| 401 | [`invalid_api_key`](https://roxyapi.com/docs/errors#invalid_api_key) | The key sent is malformed or cannot be verified. |
| 401 | [`api_key_revoked`](https://roxyapi.com/docs/errors#api_key_revoked) | The key was valid once and has since been revoked from the account page. |
| 401 | [`subscription_not_found`](https://roxyapi.com/docs/errors#subscription_not_found) | The key verifies, but the subscription behind it no longer exists. |
| 401 | [`subscription_inactive`](https://roxyapi.com/docs/errors#subscription_inactive) | The subscription behind the key is cancelled, expired or suspended, or a trial is past its end date. |
| 401 | [`publishable_key_not_allowed_on_mcp`](https://roxyapi.com/docs/errors#publishable_key_not_allowed_on_mcp) | A publishable key was used on a Remote MCP server, which takes a secret key. |
| 401 | [`invalid_client_ip`](https://roxyapi.com/docs/errors#invalid_client_ip) | A keyless request could not be attributed to a caller. |
| 401 | [`unauthorized`](https://roxyapi.com/docs/errors#unauthorized) | Authentication failed with no more specific reason to give. |
| 403 | [`forbidden`](https://roxyapi.com/docs/errors#forbidden) | The key is valid, but this request is not permitted. |
| 403 | [`origin_required`](https://roxyapi.com/docs/errors#origin_required) | A publishable key with an origin allowlist was used with no Origin header, as from a server or a native app. |
| 403 | [`origin_not_allowed`](https://roxyapi.com/docs/errors#origin_not_allowed) | The calling site is not on the origin allowlist of this publishable key. |
| 404 | [`not_found`](https://roxyapi.com/docs/errors#not_found) | Nothing is served at this path, or the identifier in it does not exist. A path miss adds suggestions, the closest real endpoints. |
| 405 | [`method_not_allowed`](https://roxyapi.com/docs/errors#method_not_allowed) | The path exists for a different HTTP method. The body lists the accepted methods in allow, as does the Allow header. |
| 409 | [`conflict`](https://roxyapi.com/docs/errors#conflict) | The request cannot be applied in the current state. |
| 410 | [`gone`](https://roxyapi.com/docs/errors#gone) | The path was removed permanently. |
| 413 | [`payload_too_large`](https://roxyapi.com/docs/errors#payload_too_large) | The request body is larger than the API accepts. A body far over the cap is refused before it reaches the API and returns a bare 413 with no JSON body. |
| 415 | [`unsupported_media_type`](https://roxyapi.com/docs/errors#unsupported_media_type) | A request with a body was sent without Content-Type: application/json. |
| 422 | [`unprocessable_entity`](https://roxyapi.com/docs/errors#unprocessable_entity) | Every field is valid, but the combination cannot be computed. |
| 429 | [`rate_limit_exceeded`](https://roxyapi.com/docs/errors#rate_limit_exceeded) | The monthly request allowance is used up. Retry-After gives the seconds to the reset. |
| 429 | [`rate_limit_per_minute`](https://roxyapi.com/docs/errors#rate_limit_per_minute) | The per-minute limit of the plan was reached. Retry-After gives the seconds to the next minute, and the monthly allowance is not charged. |
| 429 | [`rate_limited`](https://roxyapi.com/docs/errors#rate_limited) | A rate limit was reached, reported without the plan detail. |
| 429 | [`free_tier_exhausted`](https://roxyapi.com/docs/errors#free_tier_exhausted) | A keyless request has used up its trial allowance. |
| 429 | [`reports_rate_limited`](https://roxyapi.com/docs/errors#reports_rate_limited) | Too many reports were requested this minute. Retry-After gives the seconds to the next minute. |
| 500 | [`internal_error`](https://roxyapi.com/docs/errors#internal_error) | The request failed inside our service. Retry with exponential backoff. |
| 503 | [`compute_saturated`](https://roxyapi.com/docs/errors#compute_saturated) | Heavy calculations are briefly at capacity. Send the same request again after Retry-After seconds. |
| 503 | [`reports_busy`](https://roxyapi.com/docs/errors#reports_busy) | Report rendering is briefly at capacity. Send the same request again after Retry-After seconds. |
| 503 | [`report_render_timeout`](https://roxyapi.com/docs/errors#report_render_timeout) | The report took too long to render. Send the same request again. |
| Any | [`error`](https://roxyapi.com/docs/errors#error) | A fallback for a status with no more specific code. The status and the error field carry the signal. |

## Keys and access

### api_key_required

**401.** The request arrived with no key at all.

Send your key in the `X-API-Key` header, or as `Authorization: Bearer ...` from a browser. [Authentication](/docs/authentication) has a working example in curl and JavaScript. No key yet? Pick a plan on [pricing](/pricing) and yours is created the moment payment clears.

### invalid_api_key

**401.** A key was sent, but it is not one we can verify.

Almost always a copy and paste problem: a trailing space, a truncated value, or a placeholder like `your_api_key_here` left in the code. Copy the key again from the **API Keys** tab of your [account](/account?tab=keys). If you lost it, create a new one there.

### api_key_revoked

**401.** The key was valid once and has since been revoked.

Someone on your team deleted it from the account page, usually after a leak. Create a fresh key and roll it out to every deployment that still carries the old one.

### subscription_not_found

**401.** The key verifies, but the subscription behind it no longer exists.

This is what a key from a deleted account looks like. Start a new subscription on [pricing](/pricing), then swap in the key it gives you.

### subscription_inactive

**401.** The subscription behind this key is not active.

A cancelled or suspended plan keeps working until the paid period runs out, and this is the response after that. Reactivate from your [account](/account) and the same key starts working again.

### unauthorized

**401.** A generic authentication failure with no more specific code to give.

Treat it exactly like [api_key_required](#api_key_required): check that the key is present, complete, and sent on every request rather than only the first.

### forbidden

**403.** The key is valid but this particular request is not permitted.

Read the `error` field for the specific reason, then check the two publishable key entries below, which are the common causes.

### origin_required

**403.** A publishable key with an origin allowlist was used from somewhere that sent no `Origin` header.

Browsers set that header for you, so this means the call came from a server, a script, or a native mobile app. Those are server side callers: use a secret key there and keep the publishable key for the browser.

### origin_not_allowed

**403.** The page that made the call is not on the allowlist for this publishable key.

Add the site to the key on the **API Keys** tab of your [account](/account?tab=keys). Entries are plain hostnames such as `example.com`, protocol and port are ignored, and there are no wildcards, so staging and preview domains each need their own entry.

### publishable_key_not_allowed_on_mcp

**401.** A publishable key was used against an MCP server.

MCP is server side traffic, so a publishable key carries no browser origin to check there. Use a secret key in your MCP client config. [MCP setup](/docs/mcp) shows where it goes for each client.

### invalid_client_ip

**401.** A keyless request could not be attributed to a caller.

Send your API key in `X-API-Key` and the call runs against your own plan.

## Request problems

### validation_error

**400.** One or more fields in the request did not pass validation.

The body carries an `issues` array with every failure, not just the first, so one read tells you everything to change:

```json
{
  "error": "date: Invalid date",
  "code": "validation_error",
  "doc_url": "https://roxyapi.com/docs/errors#validation_error",
  "issues": [
    {
      "path": "date",
      "message": "Invalid date",
      "code": "invalid_format",
      "format": "date"
    }
  ]
}
```

`path` is the dot separated field path, or `(root)` for the body itself. `expected`, `minimum`, `maximum`, `format` and `pattern` appear when the failure has them, which is what lets an AI agent rebuild a valid payload without reading English. Dates are `YYYY-MM-DD` and times are 24 hour `HH:MM:SS`; [field formats](/docs/agent-field-formats) lists the shapes per domain.

### bad_request

**400.** The request was rejected as a whole rather than field by field.

Read the `error` field: it names the problem. The usual causes are a body that does not parse as JSON, and values that are each valid but contradict each other, such as a date range that ends before it starts.

### date_out_of_range

**400.** A date in the request lies outside the span planetary positions are served for.

Every calculation that reads the planets supports 1550-01-02 to 2650-01-22; Chiron and the asteroids cover a shorter span, and the `error` field names the dates for the body you asked about. Send a date inside the span. Numerology, biorhythm and the other date-only domains answer for any calendar date.

### invalid_branding

**400.** The branding on a report request cannot be used.

The usual cause is a logo URL that answers with something other than a PNG, JPEG, WebP or SVG image. Point `branding.logo` at the image file itself, not a page that shows it.

### logo_fetch_failed

**400.** The report logo could not be fetched.

`branding.logo` must be an HTTPS URL on a public host that answers within a few seconds with an image under 1 MB. Host the file on your own site or a CDN and send its direct URL.

### unsupported_character

**400.** The report text holds a character no report font draws.

The `error` field names the character and its code point. It came from your request: a branding field, a name or a question. Remove or replace it. Every language a report accepts and emoji are drawn.

### unprocessable_entity

**422.** The request is well formed and every field is valid, but the combination cannot be computed.

The `error` field says which values conflict. Change one of them and retry.

### unsupported_media_type

**415.** A `POST`, `PUT` or `PATCH` arrived with a body but without `Content-Type: application/json`. A request with no body at all is read as `{}`, so an endpoint whose fields are all optional answers it.

Every endpoint that takes a body takes JSON. Add the header. Most HTTP clients set it for you when you pass a JSON body rather than a string, so this usually means the body was sent as raw text.

### payload_too_large

**413.** The request body is bigger than we accept.

Our endpoints are built around one subject per request, and the largest legitimate body is a compatibility call with two people, so a body near the cap almost always means a batch was assembled by mistake. Split it into one call per subject. A body far over the cap is refused before it reaches the API and comes back as a bare `413` with no JSON body, which is deliberate: nothing oversized is read.

### method_not_allowed

**405.** The path exists, but not for this verb.

The body carries an `allow` array and the response carries an `Allow` header, both listing what the path does accept. Charts and readings are `POST` because they take a body; lookups and reference data are `GET`.

### not_found

**404.** Nothing is served at this path, or the identifier in it does not exist.

On a path miss the body adds a `suggestions` array of the closest real endpoints, plus a `docs` link to the reference for that domain, so a typo is usually one field away from the fix. On an identifier miss the `error` field names the accepted values. Identifiers are forgiving about casing and separators, so `Third Eye`, `third-eye` and `THIRD_EYE` all resolve.

### conflict

**409.** The request cannot be applied in the current state.

The `error` field says what already exists or what is already in progress. Read the current state, then retry with values that fit it.

### gone

**410.** The path was removed permanently and is not coming back.

Delete the call from your code. Nothing here needs a retry.

## Limits

### rate_limit_exceeded

**429.** You are through your monthly request allowance.

The response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used` and `X-RateLimit-Reset`, plus `Retry-After` in seconds, so a client that honours `Retry-After` stops instead of hammering. Cache the calls that never change (a natal chart for a fixed birth input is the same forever) or move up a plan on [pricing](/pricing). [Caching and cost](/docs/guides/caching) covers what is safe to keep.

### rate_limit_per_minute

**429.** You sent more requests in one minute than your plan allows. Your monthly allowance is untouched: a request refused here is not counted against it.

`Retry-After` gives the seconds until the next minute starts, which is never more than 60. Wait that long and retry, and spread steady traffic evenly across the minute instead of firing it in one burst. A backfill or batch job should pace itself under the per-minute figure listed for your plan on [pricing](/pricing).

### rate_limited

**429.** The same outcome as [rate_limit_exceeded](#rate_limit_exceeded), reported without the plan specific detail.

Read `Retry-After` for the wait. Handle it as [rate_limit_per_minute](#rate_limit_per_minute) when the wait is under a minute, and as [rate_limit_exceeded](#rate_limit_exceeded) when it runs to the monthly reset.

### free_tier_exhausted

**429.** A keyless request has used up its trial allowance.

Send your API key in `X-API-Key` to run against your own plan. [Get your API key](/account?tab=keys).

### reports_rate_limited

**429.** Too many reports were requested in this minute.

The response carries `Retry-After` in seconds. Wait that long and send the same request again.

## Something went wrong on our side

### internal_error

**500.** The request failed inside our service, not in your code.

Retry with exponential backoff. If it keeps happening, send us the `error` string, the endpoint, and the time in UTC from our [contact page](/contact) and we will trace it.

### compute_saturated

**503.** We are briefly at capacity for heavy calculations.

The response carries `Retry-After` in seconds. Wait that long and send the same request again, unchanged: nothing about it is wrong.

### reports_busy

**503.** Report rendering is briefly at capacity.

The response carries `Retry-After` in seconds. Wait that long and send the same request again, unchanged: nothing about it is wrong.

### report_render_timeout

**503.** The report took too long to render.

Send the same request again. A request that fails on our side with a `5xx` does not count against your monthly allowance.

### error

**Any status.** A fallback code for a status that has no more specific name.

The HTTP status and the `error` field are the useful signals here. Retry `5xx`, do not retry `4xx`.

## Handling this in code

Branch on `code`, retry only what is worth retrying, and print `doc_url` in your logs so the next person does not have to guess.


### JavaScript

```javascript
const res = await fetch('https://roxyapi.com/api/v2/tarot/cards/fool', {
  headers: { 'X-API-Key': process.env.ROXY_API_KEY }
});

if (!res.ok) {
  const err = await res.json();
  console.error(`[${err.code}] ${err.error} ${err.doc_url}`);
  if (err.code === 'validation_error') console.error(err.issues);
  if (['rate_limit_per_minute', 'compute_saturated'].includes(err.code)) {
    // Safe to retry after Retry-After seconds
  }
  throw new Error(err.code);
}
```

### Python

```python
import os, requests

res = requests.get(
    "https://roxyapi.com/api/v2/tarot/cards/fool",
    headers={"X-API-Key": os.environ["ROXY_API_KEY"]},
)

if not res.ok:
    err = res.json()
    print(f"[{err['code']}] {err['error']} {err['doc_url']}")
    if err["code"] == "validation_error":
        print(err["issues"])
    res.raise_for_status()
```

### curl

```bash
curl -s -o body.json -w '%{http_code}\n' \
  https://roxyapi.com/api/v2/tarot/cards/fool \
  -H "X-API-Key: $ROXY_API_KEY"

jq -r '"\(.code) \(.doc_url)"' body.json
```

Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.

## Frequently asked questions


### Is the code stable enough to switch on?

Yes. `code` is the machine readable half of the contract and is safe to branch on. The `error` sentence beside it is written for people and the wording can change at any time, so never parse it.

### Why does my error response have a doc_url field?

It is a direct link to the entry for that exact code on this page, so a failing response explains itself without a search. The URL is identical in every environment, which makes it safe to log and to paste into a bug report.

### Which errors should my client retry?

Retry `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.

### Does a failed request count toward my quota?

A `4xx` does, a `5xx` does not. Every request that reaches the API counts toward your monthly quota, success or `4xx` alike, with two exceptions: a `429` rate limit answer, and a request that fails on our side with a `5xx`, so retrying a `5xx` is free. Validate inputs before you send them and never retry a `4xx` unchanged. How to keep the bill flat with your own cache is in [caching and cost](/docs/guides/caching).

### How do I see every validation problem at once?

Read the `issues` array on a `400`. It lists every field that failed in that request, each with its path and the reason, so one retry can fix all of them.
