त्रुटियाँ

सभी त्रुटियाँ एक ही फ़ॉर्मेट में लौटाई जाती हैं - ok: false और error ऑब्जेक्ट:

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

• code: मशीन-पठनीय UPPER_SNAKE_CASE कोड, स्थिर, major bump के बिना नहीं बदलता। message पर नहीं, इस पर switch करें।
• message: मनुष्य-पठनीय व्याख्या, अंग्रेज़ी में। टेक्स्ट bump के बिना सुधारा जा सकता है।
• details: वैकल्पिक। INVALID_INPUT के लिए यह हर विफल फ़ील्ड के लिए { path, message } का ऐरे है। INVALID_FIELD के लिए हर एलिमेंट में कैनॉनिकल फ़ील्ड नाम के साथ expected जोड़ा जाता है।
• docs: वैकल्पिक, इस पेज के सेक्शन का लिंक, जब कोड के लिए विस्तृत व्याख्या मौजूद हो।
• request_id: सिर्फ़ 5xx और BAD_JSON रिस्पॉन्स में जोड़ा जाता है; सपोर्ट से संपर्क करते समय इसका हवाला दें।

HTTP कोड

स्टेटस	अर्थ
200 OK	सफलता
400 Bad Request	टूटा JSON, फ़ील्ड ग़ायब या Zod वैलिडेशन विफल
401 Unauthorized	X-Api-Key ग़ायब या अमान्य
402 Payment Required	ऊँचा टैरिफ़ / पैक चाहिए, या सब्सक्रिप्शन निष्क्रिय है
403 Forbidden	कुंजी मान्य है, लेकिन अधिकार नहीं (scope, origin, suspended)
404 Not Found	रिसोर्स, कुंजी या job मौजूद नहीं
422 Unprocessable Entity	इनपुट मान्य है, लेकिन इंजन गणना नहीं कर सका
429 Too Many Requests	Rate limit पार, क्रेडिट या spend-cap ख़त्म
500 Internal Server Error	आंतरिक त्रुटि - हमारी तरफ़ से, request_id का हवाला दें
503 Service Unavailable	AI गेटवे / कतार अस्थायी रूप से उपलब्ध नहीं

Error codes

ऑथेंटिकेशन (401)

कोड	अर्थ
MISSING_API_KEY	X-Api-Key हेडर नहीं भेजा गया
INVALID_API_KEY	कुंजी मौजूद नहीं या revoked है
MISSING_BEARER	Authorization: Bearer स्कीम चुनी गई, लेकिन टोकन ग़ायब है
WRONG_AUTH_METHOD	/v1/me/* (सिर्फ़ Bearer) पर X-Api-Key भेजा गया। कुंजी जाँचने के लिए - GET /v1/auth/keys/me; API कॉल के लिए - X-Api-Key के साथ कोई भी /v1/*

अधिकार (403)

कोड	अर्थ
INSUFFICIENT_SCOPE	कुंजी के पास इस कार्रवाई का अधिकार नहीं
DOMAIN_MISMATCH / FORBIDDEN_ORIGIN	अनुरोध का Origin कुंजी की allow-list में नहीं है
ENDPOINT_NOT_IN_SCOPE	कुंजी एंडपॉइंट्स की सूची (allowed_endpoints) तक सीमित है, और यह पाथ सूची में नहीं है। details सूची बताता है
KEY_SUSPENDED	कुंजी निलंबित है

बिलिंग (402)

कोड	अर्थ
PLAN_UPGRADE_REQUIRED	एंडपॉइंट के लिए ऊँचा टैरिफ़ या add-on पैक चाहिए
PLAN_PACK_MISMATCH	एंडपॉइंट ऐसे पैक में है जो कुंजी पर नहीं है
SUBSCRIPTION_EXPIRED	भुगतान की गई अवधि 3 दिन से ज़्यादा पहले समाप्त हो गई। समाप्ति के बाद पहले 3 दिन अनुरोध अभी भी टैरिफ़ के अनुसार सर्व होते हैं और X-Subscription-Grace-Ends हेडर के साथ आते हैं। details में expired_at, grace_ended_at और renew_url होते हैं

Rate limiting और क्रेडिट (429)

कोड	अर्थ
RATE_LIMIT	RPM लिमिट पार हो गई। रिस्पॉन्स में Retry-After: <sec> हेडर होता है
CREDITS_EXHAUSTED	क्रेडिट का मासिक बजट ख़त्म हो गया
SPEND_CAP_REACHED	AI एंडपॉइंट्स पर खर्च की सीमा पहुँच गई
KEY_BUDGET_EXHAUSTED	कुंजी ने अपना बजट (credits_cap_cycle) ख़त्म कर दिया। अकाउंट पर क्रेडिट फिर भी बचे हो सकते हैं: सीमा सिर्फ़ इसी कुंजी पर लागू है

वैलिडेशन (400)

कोड	अर्थ
INVALID_INPUT	एक या अधिक फ़ील्ड Zod वैलिडेशन में विफल रहे। details - { path, message } का ऐरे
INVALID_FIELD	बॉडी में कैनॉनिकल की जगह फ़ील्ड का छोटा नाम है। नीचे देखें
MISSING_FIELDS	अनिवार्य फ़ील्ड ग़ायब है
BAD_JSON	अनुरोध की बॉडी में टूटा JSON

400 का उदाहरण:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Invalid input: expected string, received undefined",
    "details": [
      { "path": "date", "message": "Invalid input: expected string, received undefined" },
      { "path": "time", "message": "Invalid input: expected string, received undefined" }
    ]
  }
}

INVALID_FIELD

Chart एंडपॉइंट सिर्फ़ फ़ील्ड के पूरे नाम स्वीकार करते हैं। छोटे रूप 400 के साथ अस्वीकार किए जाते हैं, चुपचाप पढ़े नहीं जाते:

भेजा गया	कैनॉनिकल फ़ील्ड	क्या अपेक्षित है
lat	latitude	दशमलव डिग्री, उत्तर धनात्मक
lng, lon, long	longitude	दशमलव डिग्री, पूर्व धनात्मक
संख्या के साथ tz, tzOffset, utcOffset, timezone_offset	timezoneOffset	UTC से घंटों की संख्या, जैसे 5.75
नाम के साथ tz, timeZone, time_zone	timezone	IANA ज़ोन का नाम, जैसे Europe/Kyiv, या auto

रिस्पॉन्स एक बार में सभी मिले फ़ील्ड सूचीबद्ध करता है, अनुरोध बॉडी के क्रम में, इसलिए नाम बदलना एक ही बार में हो जाता है:

{
  "ok": false,
  "error": {
    "code": "INVALID_FIELD",
    "message": "Unsupported fields: \"tz\", \"lat\", \"lng\". Rename them to \"timezoneOffset\", \"latitude\", \"longitude\". See details for what each one expects.",
    "details": [
      { "path": "tz",  "expected": "timezoneOffset", "message": "numeric hours from UTC, e.g. 5.75; a zone name goes in timezone" },
      { "path": "lat", "expected": "latitude",  "message": "decimal degrees, north positive" },
      { "path": "lng", "expected": "longitude", "message": "decimal degrees, east positive" }
    ],
    "docs": "https://api.astroway.info/en/errors/#invalid_field"
  }
}

path पूरा पाथ बताता है, इसलिए synastry में दिखता है कि किसका चार्ट है: chart1.lat, सिर्फ़ lat नहीं।

यही कोड तब भी लौटता है जब timezone पार्स नहीं हो पाता: ख़ाली मान, EST जैसा संक्षिप्त रूप (यह पूरे साल स्थिर -5 है, इसलिए जुलाई में न्यूयॉर्क एक घंटा गलत निकलेगा), ऐसा नाम जो टाइमज़ोन डेटाबेस में नहीं है, टेक्स्ट में लिखा ऑफ़सेट जैसे +03:00, या latitude और longitude के बिना auto। संदेश बताता है कि इसकी जगह क्या भेजें, और path ऑब्जेक्ट की ओर इशारा करता है, जैसे chart2.timezone।

दो बातें ध्यान रखने लायक़ हैं।

यह डेप्रिकेशन नहीं है। छोटे नाम कभी कॉन्ट्रैक्ट में नहीं थे और /openapi.json में बॉडी फ़ील्ड के रूप में नहीं दिखते थे। 2026-08-01 तक वे काम नहीं करते थे, बल्कि चुपचाप अनदेखे किए जाते थे: निर्देशांकों का डिफ़ॉल्ट शून्य है, इसलिए चार्ट UTC पर 0°N 0°E के लिए गिना जाता था। लग्न, भाव और उनसे निकली हर चीज़ गलत थी, और रिस्पॉन्स इस बारे में कुछ नहीं बताता था। इसलिए छोटे रूप वापस स्वीकार नहीं किए जाते: एक फ़ील्ड के लिए हमेशा के लिए दो नाम, और tz ऊपर से अस्पष्ट है (संख्या या ज़ोन का नाम)।

नेस्टेड point अलग बात है। /v1/acg-zones, /v1/acg/by-category, /v1/ccg-analysis और /v1/eclipse-analysis में point: { lat, lng } ऑब्जेक्ट घोषित फ़ील्ड नाम हैं, और वे पास होते हैं।

ग़ायब निर्देशांक: 2026-11-09 से 400

सही फ़ील्ड नाम आधा काम है। latitude और longitude के बिना बॉडी भी 200 देती थी, क्योंकि निर्देशांकों का डिफ़ॉल्ट शून्य था, और रिस्पॉन्स 0°N 0°E का वर्णन करता था।

2026-11-09 तक ऐसा अनुरोध काम करता है, लेकिन रिस्पॉन्स में Deprecation: true, Sunset, Warning और बॉडी में _warning फ़ील्ड होता है। 2026-11-09 से यह latitude is required, in decimal degrees के साथ 400 INVALID_INPUT है।

स्पष्ट latitude: 0, longitude: 0 आगे भी मान्य हैं: सवाल ग़ायब फ़ील्ड का है, मान का नहीं। timezoneOffset का डिफ़ॉल्ट शून्य बना रहता है, क्योंकि वहाँ शून्य का मतलब UTC है। city निर्देशांकों की जगह नहीं लेता: कोई उसे जियोकोड नहीं करता। जाँच सिर्फ़ उन ऑब्जेक्ट्स पर लागू होती है जिनमें एक साथ date और time दोनों हों।

गणना की त्रुटियाँ (422)

कोड	अर्थ
CALCULATION_ERROR	इनपुट मान्य है, लेकिन इंजन गणना नहीं कर सका (उदाहरण के लिए, Placidus के लिए ध्रुवीय अक्षांश)। Whole Sign / Equal या कोई दूसरी तारीख़ आज़माएँ।

सर्वर त्रुटियाँ

कोड	HTTP	अर्थ
INTERNAL_ERROR	500	अप्रत्याशित त्रुटि। हम stack trace के साथ लॉग करते हैं, request_id का हवाला दें
GATEWAY_UNAVAILABLE / AI_UNAVAILABLE / LLM_UNAVAILABLE	503	AI गेटवे उपलब्ध नहीं। एक्सपोनेंशियल backoff के साथ retry करें
QUEUE_UNAVAILABLE	503	बैकग्राउंड टास्क की कतार उपलब्ध नहीं

क्लाइंट कोड में हैंडलिंग

type ApiError = {
  ok: false;
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id?: string;
  };
};

async function chart(input: ChartInput) {
  const res = await fetch('https://api.astroway.info/v1/chart', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ASTROWAY_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });

  const body = await res.json();
  if (!body.ok) {
    throw new AstrowayError(body.error.code, body.error.message, body.error.request_id);
  }

  return body.data;
}

class AstrowayError extends Error {
  constructor(
    public code: string,
    message: string,
    public requestId?: string,
  ) {
    super(`[${code}] ${message}${requestId ? ` (request_id=${requestId})` : ''}`);
  }
}

code पर switch करें, message पर नहीं। आधिकारिक SDK (@astroway/sdk, astroway) HTTP स्टेटस के अनुसार टाइप की गई त्रुटि सबक्लास फेंकते हैं (AuthenticationError, RateLimitError, BadRequestError …), इसलिए हैंडलिंग कोड लिखने की ज़रूरत नहीं पड़ेगी।

सपोर्ट अनुरोध

संपर्क के लिए support@astroway.info पर भेजें:

1. रिस्पॉन्स से request_id (अगर यह 5xx है)
2. एंडपॉइंट और संक्षिप्त JSON body (सीक्रेट्स के बिना)
3. अपेक्षित व्यवहार बनाम वास्तविक
4. टाइमज़ोन और अनुरोध का अनुमानित समय (UTC)

जवाब - आपके प्लान के SLA के भीतर (Starter के लिए 48 घंटे, Pro के लिए 24 घंटे, Enterprise के लिए अपना)।