کدهای خطا و کاری که باید کرد

هر کدی که ممکن است برگردد، معنی‌اش، و اینکه باید دوباره تلاش کنید، چیزی را درست کنید یا صبر کنید.

خطا در سگمنتیک یک شکل ندارد. میزبان ورود داده یک شکل دارد، میزبان مدیریتی شکل دیگری، و شکل سومی روی یازده مسیر از میزبان مدیریتی بیرون می‌زند. کلاینتی که فقط یکی از این سه را می‌شناسد، روی دو تای دیگر undefined می‌خواند و شاخه‌ای را می‌رود که هیچ‌کس تستش نکرده است.

این صفحه هر کدی را که یک سطح مشتری‌رو می‌تواند برگرداند فهرست می‌کند، دسته‌بندی‌شده بر اساس کاری که باید بکنید.

#سه شکل خطا، نه یکی

محتاطانه پارس کنید. اگر error یک آبجکت است، error.code را بخوانید. اگر error یک رشته است، هیچ کدی وجود ندارد و تنها چیزی که دارید وضعیت HTTP است. اگر کلید error وجود ندارد، روی میزبان ورود داده هستید و فیلدی که می‌خواهید status است.

#میزبان ورود داده

نشانی https://in.segmentic.net یک آبجکت تخت برمی‌گرداند. هیچ فیلد code روی این میزبان وجود ندارد. مقدار ماشین‌خوان status است و همیشه یکی از دو رشته "ok" یا "error".

{"status":"error","message":"malformed JSON"}

پاسخ موفق شمارش دارد. accepted و rejected وقتی صفرند فرستاده نمی‌شوند، نه اینکه 0 بیایند. پس دسته‌ای که کامل رد شده باشد در اصل کلید accepted ندارد.

{
  "status": "ok",
  "accepted": 1,
  "warnings": [
    {
      "code": "generated_message_id",
      "field": "message_id",
      "note": "no message_id sent; retries of this event cannot be de-duplicated"
    }
  ]
}

در دسته، خرابی هر قلم با اندیس آرایه‌ای که فرستاده‌اید گزارش می‌شود، تا منطق تلاش دوباره شما بتواند آن قلم را بدون تطبیق محتوا پیدا کند. رویدادهایی که فرستاده‌اید ممکن است هنوز شناسه نداشته باشند، که خودش نیمی از دلیل رد شدنشان است.

{
  "status": "ok",
  "accepted": 2,
  "rejected": 1,
  "errors": [{"index": 1, "reason": "unknown_type: \"trak\""}]
}

رشته reason متن کامل خطاست و مقدار خودتان را هم در خود دارد. بخش پایدارش کلمه اول است، اینجا unknown_type. روی پیشوند تطبیق بدهید، نه روی کل رشته.

نوع محتوا روی هر پاسخ این میزبان application/json; charset=utf-8 است.

سه مسیر ورود داده از این شکل استفاده نمی‌کنند. POST /v1/bounce/{local} متن ساده برمی‌گرداند نه JSON. POST /v1/inbox و POST /v1/devices شکل خودشان را دارند که در دستگاه‌ها و پوش و درون‌سایتی و صندوق پیام آمده است. GET /s/{code} برای کد ناشناخته یک ۴۰۴ متن ساده و در حالت درست ۳۰۲ می‌دهد.

#میزبان مدیریتی

نشانی https://api.segmentic.net همه‌چیز را زیر error تودرتو می‌کند.

{"error":{"code":"budget_exhausted","message":"this key has spent its request budget for the minute"}}

فیلد details بخش ساختاریافته خطای اعتبارسنجی را می‌آورد، تا بتوانید انگشت بگذارید روی همان جای payload خودتان که مشکل دارد.

{
  "error": {
    "code": "batch_too_large",
    "message": "a batch may carry at most 500 events",
    "details": {"limit": 500, "sent": 501}
  }
}

فیلد need روی ۴۰۳ می‌آید و درست نام همان مجوزی را می‌گوید که کلید ندارد. به‌عمد منتشر شده است: راه دیگر این بود که مشتری تیکت بزند تا بفهمد کدام مجوز را باید بدهد.

{
  "error": {
    "code": "forbidden",
    "message": "this key does not carry campaign.send, see GET /v1/whoami for what it does carry",
    "need": "campaign.send"
  }
}

روی POST /v1/events، مقدار details به‌جای آبجکت، آرایه قلم‌به‌قلم است.

{
  "error": {
    "code": "all_events_rejected",
    "message": "no event in this batch could be accepted",
    "details": [
      {"index": 0, "reason": "missing_identity"},
      {"index": 1, "reason": "missing_identity"}
    ]
  }
}

#شکل تخت، روی یازده مسیر

یازده مسیر مدیریتی هندلرشان را با پنل به اشتراک می‌گذارند، و نویسنده خطای پنل یک رشته تخت بدون هیچ کدی می‌نویسد.

{"error":"segment not found"}

کلاینتی که فقط body.error.code را می‌خواند، روی تک‌تک این‌ها undefined می‌گیرد. مسیرها و خرابی‌هایی که این شکل را دارند:

کد invalid_report استثنای داخل استثناست: تخت است ولی کد دارد.

{"error":"قیف به دست‌کم دو مرحله نیاز دارد","code":"invalid_report"}

چهار رد شدن از نگهبان مشترک اعتبارنامه هم با همین شکل تخت به میزبان مدیریتی می‌رسند، با کد و متن فارسی: wrong_surface روی ۴۰۱، و impersonation_read_only و impersonation_forbidden و ip_not_allowed روی ۴۰۳. آخری با یک کلید API معمولی هم دیده می‌شود، چون فهرست نشانی‌های مجاز حساب روی هر اعتبارنامه‌ای اعمال می‌شود، نه فقط روی نشست مرورگر.

#روی کد شاخه بزنید، هرگز روی متن

کد قرارداد است. متن قرارداد نیست و هر وقت جمله بهتری پیدا شود عوض می‌شود.

دو پیام این را ملموس می‌کنند. متن write_key_rejected دو بار نویسه سه‌نقطه U+2026 دارد، داخل (wk_…) و (sk_seg_…)، نه سه نقطه جدا. متن قالب کلید تراکنشی بین ۸ و ۲۰۰ یک en dash با کد U+2013 دارد، نه خط تیره ساده. یکپارچه‌سازی‌ای که روی هرکدام از این دو رشته تطبیق بدهد، با نویسه‌ای می‌شکند که نویسنده‌اش هرگز تایپش نکرده است.

#درخواست را درست کنید

تلاش دوباره روی هرکدام از این‌ها یعنی فرستادن همان payload به همان رد شدن. شکل تودرتو، روی میزبان مدیریتی.

سه کد دیگر ۴۰۹ هستند و درست کردنشان کار آدم است، نه ویرایش payload.

مسیر POST /v1/audiences/validate برای فیلتر نامعتبر ۴۲۲ می‌دهد، در حالی که نقطه معادلش در پنل ۲۰۰ با valid: false می‌دهد. پنل برای فرمی که کسی دارد در آن تایپ می‌کند درست است و برای یکپارچه‌سازی‌ای که خطایش روی وضعیت شاخه می‌زند غلط.

#اعتبارنامه را درست کنید

چهارتای این‌ها ۴۰۱ هستند و با هم فرق دارند. قبل از اینکه دنبال غلط تایپی بگردید کد را بخوانید.

مسیر GET /v1/whoami یک واحد بودجه خرج می‌کند، مثل هر مسیر ساده دیگری، و مجموعه مؤثر مجوزها را برمی‌گرداند، پس یک کلاینت خوب می‌تواند موقع بالا آمدن شکست بخورد به‌جای اینکه روی همان یک فراخوانی ماهانه‌ای شکست بخورد که به مجوز نداشته‌اش نیاز دارد. تنها مسیر میزبان مدیریتی که سنجیده نمی‌شود GET /v1/status است.

curl -s https://api.segmentic.net/v1/whoami \
  -H "Authorization: Bearer sk_seg_..."

{
  "tenant_id": 42,
  "api_key_id": 7,
  "role": "analyst",
  "permissions": [
    "analytics.read", "audit.read", "campaign.read", "data.export",
    "event.read", "journey.read", "member.read", "profile.read",
    "segment.read", "settings.read", "template.read"
  ],
  "scoped": false
}

فهرست permissions مجموعه مؤثر است و الفبایی مرتب می‌شود. نقش یکی از این هفت‌تاست: owner و admin و marketer و analyst و viewer و approver و finance. کلید با نقش owner اصلا ساخته نمی‌شود، پس هیچ کلیدی tenant.transfer و tenant.delete ندارد.

مقدار scoped روی هر کلیدی که این محصول می‌تواند بسازد false است. ستون دامنه در پایگاه داده هست و خوانده هم می‌شود، ولی هیچ مسیری آن را نمی‌نویسد، پس هر کلید کل نقشش را دارد و کلید باریک‌تر از نقش هنوز ساختنی نیست.

روی میزبان ورود داده، هر دو پیام missing write key و invalid write key وضعیت ۴۰۱ دارند و هر دو دائمی‌اند. دومی برای کلید ناشناخته و کلید باطل‌شده و کلید معلق یک جواب می‌دهد، تا نشود با این نقطه فهمید چه کلیدهایی وجود دارند.

#صبر کنید

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json; charset=utf-8

{"error":{"code":"budget_exhausted","message":"this key has spent its request budget for the minute"}}

وضعیت ۴۲۹ تراکنشی شکل دیگری دارد:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 0
Content-Type: application/json; charset=utf-8

{"error":"rate limit exceeded: 2 requests per minute"}

میزبان ورود داده هرگز ۴۲۹ نمی‌دهد. هیچ محدودکننده نرخی ندارد.

#دوباره تلاش کنید

همه این‌ها ۵۰۳ هستند و همه یعنی ایراد از ماست. عقب بکشید و همان payload را دوباره بفرستید.

در کل محصول فقط یک ۵۰۳ هدر Retry-After دارد و آن هم روی میزبان ورود داده است: خرابی جست‌وجوی کلید نوشتن Retry-After: 5 می‌گذارد. بقیه ۵۰۳ها هیچ نمی‌گذارند. عقب‌نشینی خودتان را انتخاب کنید.

#پول بدهید، یا تیکت بزنید

تلاش دوباره هیچ‌کدام از این‌ها را باز نمی‌کند. کسی باید فاکتوری را پرداخت کند، پلنی را ارتقا بدهد یا مجوزی بدهد.

پیام‌های quota_* روی هر دو میزبان همیشه فارسی‌اند، هر چیزی که Accept-Language بگوید. این چهار جمله:

کد account_locked درست چهار مسیر مدیریتی را می‌بندد. ورود داده، ارسال تراکنشی، ساخت کمپین، ارسال کمپین و نوشتن سگمنت همگی موقع قفل بودن حساب باز می‌مانند، چون سوراخ در داده شما را بعدها نمی‌شود پر کرد و بدهی را بعدها می‌شود وصول کرد.

حکم سهمیه می‌داند حساب چقدر از سقف گذشته است. آن عدد به شما نمی‌رسد: پاسخ رد فقط جمله را دارد و بس. مصرف را از پنل بخوانید.

#میزبان ورود داده وضعیت دارد، نه کد

روی https://in.segmentic.net فیلد code وجود ندارد. روی وضعیت HTTP شاخه بزنید.

دقت کنید که یک شرط روی دو میزبان دو وضعیت می‌گیرد: دسته بیشتر از ۵۰۰ قلم روی POST /v1/batch وضعیت ۴۰۰ می‌گیرد و روی POST /v1/events وضعیت ۴۱۳.

مسیرهای کانال و درون‌سایتی همین شکل را با متن‌های خودشان دارند.

دو مسیر به‌عمد هرگز خرابی گزارش نمی‌کنند. GET /v1/onsite وقتی ذخیره‌گاهش پایین است 200 {"campaigns":[]} می‌دهد، چون داخل بارگذاری صفحه شما اجرا می‌شود و کند شدن یا خطای گرفتن کمپین نباید به چشم بازدیدکننده شما بیاید. POST /v1/onsite/event همیشه ۲۰۰ است، حتی وقتی نوشتن نمایش خطا داده باشد. POST /v1/hooks/... برای payload ای که نمی‌تواند تبدیلش کند 200 {"status":"ok","accepted":0} می‌دهد، چون شاپیفای و ووکامرس پاسخ غیر ۲xx را روزها تکرار می‌کنند.

#چرا یک رویداد رد شد

این ده رشته بخش پایدار errors[].reason روی میزبان ورود داده و details[].reason روی POST /v1/events هستند. مجموعه بسته است. هرچه بیرون از آن باشد invalid شمرده می‌شود.

#هشدارها، که روی ۲۰۰ می‌آیند

هشدار یعنی رویداد پذیرفته شد و چیزی اصلاح شد. خطا نیست و وضعیت را عوض نمی‌کند. هر هشدار {"code","field","note"} است و field و note وقتی خالی‌اند فرستاده نمی‌شوند.

پاسخ یک دسته وقتی پنجاه هشدار جمع کرد جمع کردن را بس می‌کند، هرچند همه‌شان در سنجه‌های کیفیت داده حساب شما شمرده می‌شوند. حواستان به generated_message_id باشد: تنها هشداری است که برایتان خرج دارد، چون یعنی رویدادی که دوباره فرستاده شود دو بار ذخیره می‌شود.

این جدول مال میزبان ورود داده است. مسیر POST /v1/events روی میزبان مدیریتی همین هشدارها را حساب می‌کند و بعد دورشان می‌ریزد، پس پاسخش هیچ‌وقت آرایه warnings ندارد و از روی آن نمی‌فهمید زمانی چسبانده شده یا شناسه پیامی ساخته شده. اگر این در را برای مهاجرت داده به کار می‌برید، حساب کنید که هیچ سیگنالی از اصلاح‌ها نمی‌گیرید.

#خطاهای ارسال تراکنشی

مسیر POST /v1/messages قدیمی‌ترین هندلر میزبان مدیریتی است و از اول تا آخر شکل تخت می‌دهد. هیچ‌کدام از خرابی‌هایش code ندارند.

همه این‌ها ۴۰۰ هستند و کل رشته error همان متن کلیدواژه است:

یک ۴۰۹ و یک ۵۰۳:

#تلاش دوباره

قاعده‌ای که SDKها پیاده کرده‌اند، و همانی که باید خودتان پیاده کنید.

هر سه SDK سگمنتیک این را در یک خط گفته‌اند: هرچه در بازه ۴۰۰ تا ۴۹۹ باشد به‌جز ۴۲۹ دائمی است و دور ریخته می‌شود؛ بقیه با عقب‌نشینی نمایی و jitter کامل تکرار می‌شوند، از پایه ۱ ثانیه تا سقف ۵ دقیقه.

تفاوت ۴۰۱ و ۵۰۳ کل دلیل جدا بودنشان روی میزبان ورود داده است. SDK وضعیت ۴۰۱ را «این کلید هرگز کار نمی‌کند» می‌خواند، متوقف می‌شود و رویدادهای بافرشده را دور می‌ریزد؛ ۵۰۳ را «بعدها دوباره امتحان کن» می‌خواند و نگهشان می‌دارد. این میزبان پیش‌تر وقتی خود جست‌وجوی کلید خطا می‌داد هم ۴۰۱ می‌داد، که ایراد ماست نه کلید شما: با پایگاه داده خاموش‌شده، هشت رویداد از هشت رویداد ۴۰۱ گرفتند و سمت مشتری نابود شدند، در حالی که لاگ خودشان می‌گفت کلید نوشتنشان نامعتبر است. حالا آن حالت ۵۰۳ با Retry-After: 5 است، و بافر دیسک پشت کالکتور درست برای همین هست که خرابی زیرساخت هیچ رویدادی را نبرد.

نتیجه برای شما: هر ۴۰۱ از ما را ایراد پیکربندی بدانید، نه گذرا. اگر روی کلیدی که دیروز کار می‌کرد ۴۰۱ انبوه دیدید، به‌راستی مشکل اعتبارنامه است، چون حالت خرابی دیگر این شکلی نیست.

#کجا تلاش دوباره محافظت‌شده است

روی هر رویداد message_id بفرستید. بدون آن ما می‌سازیمش، شما هشدار generated_message_id می‌گیرید، و تلاش دوباره بعد از timeout شبکه رویداد را دو بار ذخیره می‌کند. با آن، تلاش دوباره رایگان است.

این محافظت روی POST /v1/events نیست. آن مسیر رویدادها را بی‌آنکه ردیس را ببیند مستقیم منتشر می‌کند، پس message_id آنجا فقط شناسه رویداد است و هیچ‌چیز تکراری را نمی‌گیرد. تلاش دوباره روی این در، حتی با همان message_id، رویداد را دو بار ذخیره می‌کند. قبل از فرستادن دوباره یک خواندن بزنید.

رویداد تکراری‌زدایی‌شده به‌عنوان پذیرفته‌شده گزارش می‌شود، نه به‌عنوان تکراری. هیچ فیلد duplicate روی سیم نیست و شمارش‌ها این دو را از هم جدا نمی‌کنند. این عمدی است: منطق تلاش دوباره شما نباید مجبور باشد اهمیت بدهد، و تکراری در سهمیه شما شمرده نمی‌شود.

وقتی ردیس در دسترس نیست، بررسی تکراری‌زدایی رد می‌شود و تکراری احتمالی پذیرفته می‌شود، به‌جای اینکه رویداد از دست برود.

ارسال تراکنشی بازپخش‌شده علامت دارد. فیلد replayed را در نتیجه بخوانید تا «پیش‌تر این کار را کردیم» را از «همین حالا کردیم» جدا کنید، که وقتی تلاش اولتان timeout خورده و نمی‌دانید کدامش شده مهم است.

#شناسه پیگیری برای تیکت

هر پاسخ از هر میزبان هدر X-Segmentic-Trace دارد، شانزده نویسه شانزده‌شانزدهی.

HTTP/1.1 503 Service Unavailable
X-Segmentic-Trace: 4f2a9c81b0d3e756
Content-Type: application/json; charset=utf-8

{"error":{"code":"ingest_unavailable","message":"could not queue these events; retry"}}

در بدنه خطا نیست. از هدر لاگش کنید و در تیکت پشتیبانی بیاوریدش: همین است که به ما اجازه می‌دهد درست همان درخواست را در لاگ پیدا کنیم، نه دسته‌ای از درخواست‌های شبیه هم. اگر خودتان شناسه پیگیری دارید، آن را با همین هدر روی درخواست بفرستید: وقتی بین ۸ تا ۶۴ نویسه شانزده‌شانزدهی باشد، با حروف کوچک رعایتش می‌کنیم و در پاسخ برمی‌گردانیمش. هرچیز دیگری دور ریخته می‌شود و شناسه خودمان جایش می‌نشیند، چون این مقدار داخل خط‌های لاگ ما می‌رود.

نام هدر مال خودمان است و traceparent استاندارد کنسرسیوم وب نیست، چون پشتش نه تصمیم نمونه‌گیری هست و نه سلسله‌مراتب span، و هدری که شبیه traceparent باشد ولی نباشد اولین کسی را که ابزار ردیابی واقعی را به آن وصل کند گمراه می‌کند.

#آنچه در بدنه خطا نیست

این‌ها را نوشته‌ایم چون هرکدام چیزی است که خواننده دنبالش می‌گردد و پیدا نمی‌کند.

• فیلد request_id وجود ندارد. شناسه پیگیری فقط در هدر است.
• فیلد message_fa وجود ندارد. شکل مدیریتی code و message و details و need دارد و بس. هرجا متنی فارسی باشد، در همان message فارسی است.
• کد جدا برای خطاهای گزارش وجود ندارد. سیزده خطای اعتبارسنجی موتور گزارش‌ها همه در یک کد invalid_report جمع می‌شوند. نه تای آن‌ها جمله فارسی کاتالوگ را در error می‌گذارند؛ چهار تای دیگر، یعنی نام رویداد بلند و فیلتر زیاد و کلید ویژگی بلند و مقدار ویژگی بلند، از شاخه پیش‌فرض رد می‌شوند و متن انگلیسی خود خطا را می‌آورند، مثل analytics: too many filters. پس زبان error روی این دو مسیر ثابت نیست. بدون خواندن آن رشته هم نمی‌توانید «مراحل قیف زیاد است» را از «بازه زمانی خیلی گسترده است» جدا کنید.
• فیلدهای used و limit روی ۴۰۲ وجود ندارند. حکم سهمیه هر دو را حساب می‌کند و قبل از نوشتن پاسخ دور می‌ریزد.
• بودجه باقی‌مانده در GET /v1/whoami وجود ندارد. پنج فیلد برمی‌گرداند و هیچ‌کدام بودجه نیست.
• **هدرهای X-RateLimit-* روی بودجه مدیریتی وجود ندارند.** فقط روی POST /v1/messages هستند، آن هم فقط وقتی محدودیت نرخی تنظیم شده باشد که به‌طور پیش‌فرض نشده است. سقف‌ها را ببینید.

مرتبط: سقف‌ها و محدودیت نرخ، API ورود داده، API مدیریتی.