RoxyAPI
Quick StartAGENTS.mdSDKMCP SetupFree StartersAPI Playground
  1. Docs
  3. Agent Reference
  5. Common Mistakes

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.