GraphQL त्रुटियाँ

Resolver errors HTTP 200 के साथ आती हैं

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

// 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 है:

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 खर्च करती है:

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

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

Error का आकार

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

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

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

extensions.code का उपयोग error code reference के साथ करें, या इसे explainError को पास करें।

आंशिक सफलता

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

{
  history: postHistory(lastDays: 7)
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}

{
  "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 को न फेंकें — इससे वह डेटा भी चला जाएगा जिसके लिए आपसे पहले ही शुल्क लिया जा चुका है।

Multi-network पोस्ट्स पर आंशिक सफलता

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

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

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

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

Retries

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 करने से पहले पुष्टि करें कि वह प्रभावी हुआ या नहीं।

सामान्य statuses

`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 न तो की गई और न ही उसका शुल्क लिया गया।

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

GraphQL त्रुटियाँ

Resolver errors HTTP 200 के साथ आती हैं

Error का आकार

आंशिक सफलता

Multi-network पोस्ट्स पर आंशिक सफलता

Retries

सामान्य statuses

​Resolver errors HTTP 200 के साथ आती हैं

​Error का आकार

​आंशिक सफलता

​Multi-network पोस्ट्स पर आंशिक सफलता

​Retries

​सामान्य statuses

Resolver errors HTTP 200 के साथ आती हैं

Error का आकार

आंशिक सफलता

Multi-network पोस्ट्स पर आंशिक सफलता

Retries

सामान्य statuses