# Common Mistakes (verified from production)

LLMs frequently produce broken RoxyAPI code in these specific ways. Cross-checked against production logs.

## Astrology

- Horoscope path is `GET /astrology/horoscope/{sign}/daily` (weekly and monthly too). Sign is a PATH param, not a query param. Never `?sign=aries`.
- Birth chart is `POST /astrology/natal-chart` (not `/birth-chart`). POST with JSON body, not GET.
- Daily horoscope response fields: `overview`, `love`, `career`, `health`, `finance`, `advice`, `luckyNumber`, `luckyColor`. No `horoscope`, `lucky_number`, or `mood` fields.
- Western `timezone` is REQUIRED (no default). Vedic `timezone` is optional with default `5.5` (IST).

## Vedic

- Body is `{ date, time, latitude, longitude, timezone }` — NOT `{ year, month, day, hour }`.
- Manglik dosha response uses `present` (boolean). Not `isManglik`. Fields: `{ present, severity, description, exceptions, remedies, effects }`.
- Kalsarpa: `present` not `hasKalsarpaDosha`. Severity is `"Mild"` / `"Moderate"` / `"Severe"` — not `"None"` / `"Partial"` / `"Full"`.
- Guna Milan compatibility: field is `total` (not `total_score`), `maxScore` is always 36, breakdown items use `category` (not `name`).
- Dasha endpoints: `POST /dasha/major` (not `/dasha/complete`), `POST /dasha/sub/{mahadasha}` (not `/dasha/antardashas`).
- KP chart is `POST /kp/chart` (not `/kp/birth-chart`). KP ruling planets do NOT need `date` / `time` — they use `datetime` or default to now.
- Panchang detailed takes NO `time` field — only `date`, `latitude`, `longitude`, optional `timezone`.

## Numerology

- Life path, chart, and personal year all take `{ year, month, day }` integers — NOT a `birthDate` string.
- Chart requires `fullName` (not `name`). Expression requires `fullName`. Name is birth certificate name.
- Personal year body: `{ month, day, year? }` — `year` is TARGET year (defaults to current), not birth year.
- Compatibility body: flat `person1` / `person2` objects, each with any of `lifePath`, `expression`, `soulUrge`, or `fullName` + `year` + `month` + `day`.

## Tarot

- Daily body field is `seed` (not `userId`). Body is optional; omit for random daily card.
- Daily response field is `dailyMessage` (not `message`).
- Spread responses return `positions[]` where each has a `card`. No top-level `cards[]` on spread endpoints. Access via `positions[i].card`.
- Spread endpoints are under `/spreads/`: `POST /spreads/three-card`, `POST /spreads/celtic-cross`, `POST /spreads/love`. Not `/three-card` or `/love-spread`.
- Yes/No response: `strength` (not `confidence`). Values: `"Strong"` or `"Qualified"` only. No `"Weak"`.
- Card IDs are kebab-case: `the-fool`, `ace-of-cups`, `three-of-swords`. Not numeric like `major-01` or `cups-03`.
- Draw endpoint: `count` 1 to 78, optional `seed`, optional `allowReversals` (default `true`), optional `allowDuplicates` (default `false`).

## Biorhythm

- Forecast and critical-days both use `{ birthDate, startDate?, endDate? }`. Forecast max window is 90 days, critical-days max is 180 days.
- Compatibility body uses nested objects: `{ person1: { birthDate }, person2: { birthDate }, targetDate? }` — NOT flat `person1BirthDate`.
- Daily body is optional `{ seed?, date? }`.

## I-Ching

- Daily is POST (`/iching/daily`). Random cast is GET (`/iching/cast`). Seeded daily cast is POST (`/iching/daily/cast`). Do not confuse the three.
- Hexagram detail path param is an INTEGER 1 to 64: `GET /iching/hexagrams/1`, not `GET /iching/hexagrams/qian`.

## Angel Numbers

- By-number path param is a STRING: `GET /angel-numbers/numbers/1111`. If you pass integer `1111` to a typed client it may fail.
- `/lookup` works for any positive integer, not just canonical angel numbers. It uses digit-root fallback — never generate "only 111/222/333/etc are valid" validation logic.

## All Endpoints

- All POST endpoints: include `Content-Type: application/json` header.

## SDK Usage (@roxyapi/sdk or roxy-sdk)

- TypeScript: initialize with `createRoxy(apiKey)`, named export from `@roxyapi/sdk`. Not `new Roxy()`. Every method returns `{ data, error, response }`. Check `error` first — mutually exclusive with `data`. Pass structured args: `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }` — never positional.
- Python: `from roxy_sdk import create_roxy`, pass kwargs (`sign="aries"`), never positional. Async variants end with `_async`. Errors raise `RoxyAPIError` — catch and switch on `e.code` (not `e.error`).
- Do not guess method names. They come from OpenAPI `operationId`, not URL paths.
- Never call Roxy from client-side code. API keys belong on the server.