الأخطاء والحدود

غلاف الخطأ

كل خطأ، من كل نقطة، له الشكل نفسه. لا توجد صيغة ثانية ولا استجابة نصية مجردة.

HTTP/1.1 422 Unprocessable Entity
content-type: application/json; charset=utf-8
x-request-id: req_...

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload failed validation.",
    "request_id": "req_...",
    "details": {
      "issues": [
        { "path": "to", "message": "must be an E.164 number, e.g. +9665XXXXXXXX" }
      ]
    }
  }
}

أخطاء التحقق

الطلب غير السليم يعطي 422 مع قائمة مقروءة آليا بما كان خطأ.

• إخفاقات التحقق هي 422 لا 400. والـ 400 الوحيد في الـ API كلها هو غياب سياق مساحة العمل.
• docs.pages.errors.validation.rules.issues
• القيمة التي أرسلتها لا تُعاد إليك أبدا، فتسجيل الخطأ آمن حتى لو حمل الطلب شيئا حساسا.
• معظم أجسام الكتابة صارمة: الحقل المجهول خطأ لا مفتاح يُتجاهل. والاسم المكتوب خطأ يخفق بصوت عال.

رموز الأخطاء

الدليل العام كاملا: 72 رمزا، مجموعة كما تجمعها المنصة. وعمود الرسالة هو نص الـ API الإنجليزي نفسه منقولا حرفيا — فهو بيانات استجابة لا نثر توثيق، ولهذا لم يُترجم.

قد تُضاف رموز إلى هذه القائمة. أما الرمز الموجود فلا يغيّر معناه ولا يختفي دون رفع إصدار الـ API.

حالات HTTP

الحالة تخبرك بصنف المشكلة؛ والرمز يخبرك أيّها.

تقسيم الصفحات

قوائم النتائج مقسّمة بالـ cursor. اقرأ page.next_cursor وأعده في after؛ وتوقّف حين تصير has_more بقيمة false.

curl "https://whats.azzamkh.sa/api/v1/messages?limit=50" \
  -H "Authorization: Bearer $WA_API_KEY"

# 200 OK
# {
#   "data": [ { "id": "msg_...", ... } ],
#   "page": { "next_cursor": "bXNnXzAxSj...", "has_more": true }
# }

# Follow the cursor. Send it back verbatim; it is opaque.
curl "https://whats.azzamkh.sa/api/v1/messages?limit=50&after=bXNnXzAxSj..." \
  -H "Authorization: Bearer $WA_API_KEY"

• قيمة limit الخارجة عن المدى أو غير القابلة للقراءة تُحصر ولا تُرفض. فطلب 5000 صف يعيد 100.
• الـ cursor مبهم. أعده كما هو ولا تفكّه — والمشوّه منه يُتجاهل فتحصل على الصفحة الأولى ثانية بصمت.
• معظم القوائم الأحدث أولا، لكن القوالب الأقدم أولا. لا تفترض اتجاها؛ اتبع الـ cursor.
• قيمة next_cursor تكون null في الصفحة الأخيرة. كرّر على has_more لا على مصفوفة data فارغة.

تحديد المعدل

المسارات المحدودة تجيب بـ 429 مع الـ headers القياسية وتلميح إعادة المحاولة في الجسم.

HTTP/1.1 429 Too Many Requests
ratelimit-limit: 600
ratelimit-remaining: 0
ratelimit-reset: 37
retry-after: 37

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry later.",
    "request_id": "req_...",
    "details": { "bucket": "messages.send", "retry_after_s": 37 }
  }
}

• كل القيم بالـ ثواني لا طوابع زمنية.
• تغيب هذه الـ headers حين يكون تحديد المعدل مطفأ في البيئة. عامل غيابها انعدامَ معلومة لا حصةً بلا حد.
• المحدِّد يخفق مفتوحا: إن تعذّر مخزنه سُمح بالطلبات. فلا تعتمد عليه آلية صحّة أبدا.
• الرمز PROVIDER_RATE_LIMITED شيء آخر: مزوّد واتساب الأعلى يخنق القناة، ولا header يخبرك متى يتوقف.

ماذا تعيد

أعد المحاولة بتباعد أسّي وعشوائية، وأرسل دائما Idempotency-Key مع أي كتابة حتى لا تكرر إعادة المحاولة شيئا.