> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL त्रुटियाँ

> Ayrshare GraphQL API त्रुटियों की रिपोर्ट कैसे करता है, malformed requests पर HTTP status codes से लेकर errors array, आंशिक सफलता, idempotent retries, और rate limits तक।

<h2 id="resolver-errors-arrive-with-http-200">
  Resolver errors HTTP 200 के साथ आती हैं
</h2>

Error handling लिखने से पहले जानने योग्य यह सबसे महत्वपूर्ण बात है।

GraphQL over HTTP specification का पालन करते हुए, हमारे resolvers तक पहुँचने वाली request **किसी ऑपरेशन के विफल होने पर भी HTTP 200** लौटाती है। विफलता की रिपोर्ट response body के अंदर की जाती है, status code द्वारा नहीं।

इसलिए यह जाँच काम नहीं करती:

```javascript theme={"system"}
// WRONG - will treat a failed request as a success
if (response.ok) {
  return "everything worked";
}
```

इसके बजाय body जाँचें। कुछ transport errors, जैसे असमर्थित `Content-Type` के लिए 415, की body खाली होती है, इसलिए parse करने से पहले जाँच लें कि response JSON है:

```javascript theme={"system"}
if (!response.headers.get("content-type")?.includes("json")) {
  throw new Error(`GraphQL request failed with HTTP ${response.status}`);
}

const result = await response.json();

if (result.errors) {
  for (const error of result.errors) {
    // Errors caught before execution have no extensions, so read it safely.
    console.log(error.message, error.extensions?.status);
  }
}
```

कुछ विफलताएँ कुछ भी चलने से पहले ही पकड़ ली जाती हैं। इनमें से कोई भी resolver तक नहीं पहुँचती और न ही कोई API call खर्च करती है:

<ul class="custom-bullets">
  <li>Malformed request एक error status लौटाती है: अमान्य JSON या अनुपस्थित <code>query</code> के लिए <strong>HTTP 400</strong>, 64 KB से बड़ी body के लिए <strong>413</strong>, <code>POST</code> के अलावा किसी अन्य method के लिए <strong>405</strong>, और असमर्थित <code>Content-Type</code> के लिए <strong>415</strong>।</li>
  <li>Schema के लिए अमान्य query <strong>HTTP 400</strong> केवल तभी लौटाती है जब आपकी request <code>Accept: application/graphql-response+json</code> भेजती है। इसमें syntax error, अज्ञात फ़ील्ड, गलत argument type, अमान्य enum value, और <a href="/docs/apis/graphql/limits#query-limits">query सीमाओं</a> से अधिक query शामिल हैं। यदि आप <code>Accept: application/json</code> भेजते हैं, या कोई <code>Accept</code> header नहीं भेजते, तो वही error <strong>HTTP 200</strong> लौटाती है। दोनों ही स्थितियों में, body में एक <code>errors</code> array होता है और कोई <code>data</code> नहीं होता।</li>
</ul>

Execution शुरू होने के बाद, resolver-स्तर की input validation और API विफलताएँ — जिनमें authentication, authorization, upstream rate limits, और upstream 5xx responses शामिल हैं — `errors` array के साथ HTTP 200 लौटाती हैं।

<h2 id="the-error-shape">
  Error का आकार
</h2>

हर resolver error `extensions` में अपना HTTP-जैसा API status रखती है:

```json theme={"system"}
{
  "data": { "postHistory": null },
  "errors": [
    {
      "message": "Rate limit exceeded",
      "path": ["postHistory"],
      "extensions": {
        "status": 429,
        "retryAfter": 7
      }
    }
  ]
}
```

<ul class="custom-bullets">
  <li><code>message</code> — मनुष्यों के पढ़ने योग्य विवरण। हम resolver error messages से API keys और अन्य credentials हटा देते हैं, लेकिन आपके द्वारा भेजे गए किसी मान के बारे में error, जैसे गलत type का variable, उस मान को दोहरा सकती है। Log करने से पहले <code>message</code> को संभावित रूप से संवेदनशील मानें।</li>
  <li><code>path</code> — आपकी query का कौन-सा फ़ील्ड विफल हुआ। एक request में कई फ़ील्ड्स होने पर, इसी से आप पता लगाते हैं कि कौन-सा।</li>
  <li><code>extensions.status</code> — वह HTTP status जो समकक्ष REST call ने लौटाया होता। इसी के आधार पर निर्णय लें।</li>
  <li><code>extensions.code</code> — संख्यात्मक Ayrshare error code, जब अंतर्निहित endpoint इसे प्रदान करता है।</li>
  <li><code>extensions.retryAfter</code> — upstream कोटा या rate-limit वाले 429s पर तब मौजूद होता है जब retry delay उपलब्ध हो। यह प्रति-request dispatch-budget वाले 429 पर मौजूद नहीं होता।</li>
</ul>

`extensions.code` का उपयोग [error code reference](/docs/errors/overview) के साथ करें, या इसे `explainError` को पास करें।

<h2 id="partial-success">
  आंशिक सफलता
</h2>

यदि कोई request कई चीज़ें माँगती है और केवल कुछ ही सफल होती हैं, तो आपको `data` और `errors` **दोनों** मिलते हैं:

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

```json theme={"system"}
{
  "data": {
    "history": { "history": [{ "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }], "refId": "9d2a7c41f0b8e6d35a1c", "count": 1, "lastUpdated": "2026-09-24T12:00:00.000Z", "nextUpdate": "2026-09-24T12:00:00.000Z" },
    "analytics": null
  },
  "errors": [
    {
      "message": "Rate limit exceeded",
      "path": ["analytics"],
      "extensions": { "status": 429 }
    }
  ]
}
```

`history` सफल रहा और उसका डेटा उपयोग योग्य है। केवल `analytics` को retry करने की आवश्यकता है। `errors` मौजूद होने के कारण पूरे response को न फेंकें — इससे वह डेटा भी चला जाएगा जिसके लिए आपसे पहले ही शुल्क लिया जा चुका है।

<h2 id="partial-success-on-multi-network-posts">
  Multi-network पोस्ट्स पर आंशिक सफलता
</h2>

कई नेटवर्क्स पर भेजी गई पोस्ट कुछ पर सफल और अन्य पर विफल हो सकती है। इसे GraphQL error के रूप में **रिपोर्ट नहीं** किया जाता, क्योंकि ऑपरेशन स्वयं सफल रहा — इसने ठीक वही किया जो आपने माँगा था और आपको बता रहा है कि क्या हुआ।

परिणाम तीनों नतीजों को अलग-अलग करता है:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [FACEBOOK, INSTAGRAM]
    idempotencyKey: "multi-network-hi-001"
  }) {
    status
    postIds { platform postUrl }
    errors { platform message code }
    blocked { platform message }
  }
}
```

<ul class="custom-bullets">
  <li><code>postIds</code> — वे नेटवर्क्स जिन पर प्रकाशन हुआ, उनके post URLs के साथ। केवल सफलताएँ।</li>
  <li><code>errors</code> — वे नेटवर्क्स जो विफल हुए, कारण के साथ।</li>
  <li><code>blocked</code> — वे नेटवर्क्स जिन्हें प्रयास से पहले ही रोक दिया गया, उदाहरण के लिए बार-बार होने वाली निश्चित विफलताओं के बाद प्रति-नेटवर्क circuit breaker द्वारा। ये उन provider प्रयासों से अलग हैं जिन्होंने errors लौटाईं।</li>
</ul>

यदि **कोई भी** नेटवर्क विफल होता है तो `status` `"error"` होता है, इसलिए यह इस बात का विश्वसनीय संकेत नहीं है कि कुछ भी प्रकाशित नहीं हुआ। क्या प्रकाशित हुआ, यह जानने के लिए `postIds` पढ़ें।

<h2 id="retries">
  Retries
</h2>

**GraphQL API कभी भी स्वचालित रूप से retry नहीं करता।** यदि कोई request विफल होती है, तो आपकी ओर से चुपचाप दोबारा कोई प्रयास नहीं किया गया।

यह mutations के लिए सबसे अधिक मायने रखता है। `createPost` `idempotencyKey` उपलब्ध कराता है: पहले प्रयास से पहले एक अद्वितीय key बनाएँ, फिर हर retry के लिए वही key और समान payload दोबारा उपयोग करें। पूर्ण हो चुका retry write को दोहराने के बजाय मूल परिणाम को दोबारा लौटाता है। अस्पष्ट response के बाद नई key पर स्विच न करें।

`boostFacebookPost` और `instagramBoostPost` भी एक `idempotencyKey` लेते हैं, और यह वास्तविक पैसे की सुरक्षा करता है। समान key और समान arguments के साथ retry, दूसरा ad बनाने और उसका भुगतान करने के बजाय, `idempotentReplayed: true` चिह्नित मूल परिणाम लौटाता है। एक key दोनों Meta प्लेटफ़ॉर्म्स पर आपके पूरे खाते को कवर करती है, इसलिए Facebook boost की key को Instagram boost के लिए कभी दोबारा उपयोग न करें।

जब कोई key अस्वीकार की जाती है, तो `extensions.status` बताता है कि क्यों। `createPost` तब 409 लौटाता है जब पहला प्रयास अभी भी प्रोसेस हो रहा हो, इसलिए प्रतीक्षा करें और उसी key के साथ retry करें, और 400 तब जब payload पहले प्रयास से भिन्न हो। Boost mutations दोनों स्थितियों में 409 लौटाते हैं, और तब भी जब key का उपयोग दूसरे प्लेटफ़ॉर्म पर boost के लिए किया गया हो।

अन्य writes, जैसे `addComment`, में कोई idempotency key नहीं होती। यदि उनका response खो जाता है, तो दूसरा प्रयास सुरक्षित है या नहीं, यह तय करने से पहले सोशल नेटवर्क या API की state जाँचें।

दो अलग-अलग सीमाएँ दोनों 429 रिपोर्ट करती हैं, और उन्हें अलग-अलग तरीके से संभालना पड़ता है। Dispatch budget root फ़ील्ड्स को केवल तभी अस्वीकार करता है जब उसी request में पाँच API calls पहले ही शुरू हो चुकी हों, और इसका message `Query exceeds the per-request dispatch budget` से शुरू होता है: उन फ़ील्ड्स को अधिकतम पाँच वाली requests में बाँट दें, प्रतीक्षा करने की आवश्यकता नहीं है। कोई भी अन्य 429 एक rate limit या कोटा है: मौजूद होने पर `extensions.retryAfter` सेकंड प्रतीक्षा करें, अन्यथा retry करने से पहले back off करें, और केवल उन्हीं फ़ील्ड्स को retry करें जो विफल हुए। किसी **read** पर 5xx के लिए, retry करना सुरक्षित है, एक अपवाद के साथ: `generatePost` एक query है, लेकिन retry AI generator को दोबारा कॉल करता है, एक और API call के रूप में गिना जाता है, और अलग टेक्स्ट लौटाता है। Idempotency के बिना किसी write पर 5xx के लिए, retry करने से पहले पुष्टि करें कि वह प्रभावी हुआ या नहीं।

<h2 id="common-statuses">
  सामान्य statuses
</h2>

| `extensions.status` | अर्थ | क्या करें |
| - | - | - |
| 400 | अमान्य input जिसे हमारे API ने अस्वीकार किया | Request ठीक करें; retry करने से मदद नहीं मिलेगी |
| 401 | अनुपस्थित या अमान्य API key | `Authorization` header जाँचें |
| 402 | Plan में यह सुविधा शामिल नहीं है | अपना plan जाँचें |
| 403 | Key मान्य है लेकिन इस कार्य के लिए अनुमति नहीं है | Profile keys और plan जाँचें |
| 404 | आपने जो माँगा वह मौजूद नहीं है | Id सत्यापित करें |
| 409 | Idempotency key उपयोग में है: पहली request अभी भी चल रही है, या किसी boost key का उपयोग भिन्न arguments के साथ किया गया | यदि पहली request अभी भी चल रही है, तो प्रतीक्षा करें और बिना बदलाव के retry करें; अन्यथा नए ऑपरेशन के लिए नई key का उपयोग करें |
| 429 | Rate limit, कोटा, या dispatch budget | यदि message में dispatch budget का उल्लेख है, तो request को बाँट दें। अन्यथा `retryAfter` तक प्रतीक्षा करें, या यदि यह अनुपस्थित हो तो back off करें |
| 500 | हमारी ओर कुछ गलत हुआ | किसी read को retry करें (`generatePost` को नहीं, जिसका दोबारा शुल्क लगता है); जहाँ समर्थित हो वहाँ वही idempotency key दोबारा उपयोग करें, अन्यथा retry करने से पहले write को सत्यापित करें |

Execution से पहले स्वयं GraphQL द्वारा उठाई गई errors, जैसे अज्ञात फ़ील्ड, गलत argument type, या अमान्य enum value, में कोई `extensions.status` नहीं होता। ऊपर बताए अनुसार, वे आपके `Accept` header के आधार पर HTTP 400 या 200 लौटाती हैं। इनका अर्थ है कि query स्वयं गलत है, और कोई API call न तो की गई और न ही उसका शुल्क लिया गया।


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.