कॉन्सेप्ट्स

Errors

Errors मानक HTTP status codes इस्तेमाल करते हैं और उनका JSON आकार हमेशा एक जैसा होता है।

Error फ़ॉर्मैट#

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not have the scope posts:write"
  }
}

code स्थिर रहता है: अपने कोड में इसी का इस्तेमाल करें।
message इंसानों के पढ़ने के लिए है और बदल सकता है।
कुछ errors code और message के साथ अतिरिक्त फ़ील्ड्स भी जोड़ते हैं (उदाहरण के लिए validation error में अमान्य फ़ील्ड)।

Error codes#

Status	Code	मतलब · क्या करें
400	`VALIDATION_ERROR`	कोई parameter या body फ़ील्ड मौजूद नहीं है या अमान्य है। Request ठीक करें; उसे जैसा है वैसा retry न करें।
400	`INVALID_JSON`	Body वैध JSON नहीं है। `Content-Type: application/json` और एक वैध body भेजें।
401	`INVALID_API_KEY`	Key मौजूद नहीं, ग़लत फ़ॉर्मैट में या revoke की हुई है। `Authorization` header जाँचें।
403	`INSUFFICIENT_SCOPE`	Key के पास वह scope नहीं है जो इस endpoint को चाहिए। सही scopes के साथ एक key बनाएँ।
403	`DEVELOPER_ACCESS_REVOKED`	इस अकाउंट का डेवलपर एक्सेस निलंबित या revoke कर दिया गया है। developers@linework.app से संपर्क करें।
403	`PROFILE_INCOMPLETE`	Write endpoints इस्तेमाल करने से पहले अकाउंट में प्रोफ़ाइल फ़ोटो और कवर जोड़ें।
403	`CHAT_NOT_ALLOWED`	Anti-spam नियम इस मैसेज की अनुमति नहीं देता: उस व्यक्ति ने आपको नहीं लिखा है और वह आपको फ़ॉलो नहीं करता।
403	`CHAT_BLOCKED`	आप में से किसी एक ने दूसरे को ब्लॉक किया है। Retry न करें।
403	`STORE_BLOCKED`	इस स्टोर ने आपको ब्लॉक किया है।
403	`USER_UNAVAILABLE`	यूज़र उपलब्ध नहीं है (ब्लॉक, प्राइवेट या निलंबित)।
403	`FORBIDDEN`	इस अकाउंट के लिए यह action अनुमत नहीं है (उदाहरण के लिए किसी और की पोस्ट एडिट करना)।
404	`NOT_FOUND`	Resource मौजूद नहीं है या आप उसे नहीं देख सकते।
409	`CONFLICT`	Request मौजूदा स्थिति से टकराती है (उदाहरण के लिए किसी ऑर्डर को दो बार शिप करना)।
413	`PAYLOAD_TOO_LARGE`	Body या अपलोड की गई फ़ाइल बहुत बड़ी है। मीडिया के साथ पोस्ट में मीडिया की सीमाएँ देखें।
429	`RATE_LIMITED`	बहुत ज़्यादा requests, या कोई दैनिक quota ख़त्म हो गया है। `Retry-After` तक इंतज़ार करें। Rate limits देखें।
500	`INTERNAL_ERROR`	हमारी तरफ़ कुछ गड़बड़ हुई। बाद में backoff के साथ retry करें।

समय के साथ नए codes जोड़े जा सकते हैं: किसी अनजान code को उसके HTTP status के सामान्य मतलब के अनुसार हैंडल करें।

Retry करें या नहीं?#

Status	Retry?
400, 401, 403, 404, 409, 413	नहीं। पहले request, key या अकाउंट ठीक करें।
429	हाँ, `Retry-After` के बाद।
500, 502, 503, 504	हाँ, exponential backoff के साथ। जो writes idempotent नहीं हैं (उदाहरण के लिए `POST /posts`), उनके लिए पहले जाँच लें कि action पहले ही नहीं हो चुका है।

Handler का उदाहरण#

const res = await fetch(url, options);
if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: { code: "UNKNOWN" } }));
  switch (error.code) {
    case "RATE_LIMITED": /* wait Retry-After, then retry */ break;
    case "INVALID_API_KEY":
    case "DEVELOPER_ACCESS_REVOKED": /* stop the bot and alert someone */ break;
    case "CHAT_NOT_ALLOWED": /* skip this user */ break;
    default: throw new Error(`${res.status} ${error.code}: ${error.message}`);
  }
}

r = s.post(url, json=body, timeout=30)  # s = requests.Session() with the Authorization header
if not r.ok:
    err = r.json().get("error", {})
    code = err.get("code")
    if code == "RATE_LIMITED":
        ...  # wait Retry-After, then retry
    elif code in ("INVALID_API_KEY", "DEVELOPER_ACCESS_REVOKED"):
        ...  # stop the bot and alert someone
    elif code == "CHAT_NOT_ALLOWED":
        ...  # skip this user
    else:
        raise RuntimeError(f"{r.status_code} {code}: {err.get('message')}")