ابدأ من هنا

الأخطاء وإعادة المحاولة

حلّل غلاف أخطاء JSON القياسي وقرّر متى تكون إعادة المحاولة آمنة.

غلاف الخطأ

تستخدم إخفاقات واجهة JSON API كائن error واحدًا في المستوى الأعلى، يتضمن message مقروءة للبشر، وstatus برمز HTTP الرقمي، وcode ثابتًا اختياريًا. يشير عقد OpenAPI إلى هذا المخطط في حالات الإخفاق المتوقعة وغير المتوقعة.

استجابة الخطأ
{
  "error": {
    "code": "invalid_request",
    "message": "A verified From domain is required",
    "status": 403
  }
}

أخطاء العميل

صحِّح أخطاء الإدخال 400 قبل إعادة المحاولة. استبدل بيانات الاعتماد غير الصالحة أو ألغِها بعد 401. يتطلب 402 استحقاقًا مدفوعًا، ويشير 403 إلى حدّ سياسة أو صلاحية، ويعني 404 مورد مفقودًا ضمن نطاق المستأجر، ويمثّل 409 تعارضًا في الحالة أو في مفتاح عدم التكرار (idempotency key)، ويعني 413 تجاوز حدود المرفقات، ويغطي 422 إخفاق التحقق من الصحة أو المنع.

قرارات إعادة المحاولة

Do not automatically retry authentication, validation, suppression, conflict, or 402 subscription_required failures. A 402 means the workspace has no active subscription; choose a plan, then send. A 423 with code sender_paused means the exact From identity is paused. A 423 with code account_paused means the workspace is paused for review: the body includes the measured bounce and complaint rates and the limits they crossed (bounce_rate vs bounce_limit, complaint_rate vs complaint_limit). Stop that stream. A 429 with code daily_limit_reached is the workspace daily ladder, not a short backoff. Wait until resets_at (midnight UTC). Retry-After is the seconds until then. hourly_limit_reached waits until the next UTC hour. gmail_recipient_limit waits until midnight UTC. The refused message was not queued. Other 429 responses (quota_exhausted) wait until that monthly, per-sender, or attachment limit resets. A caller may retry a transient 502 or 503 with bounded exponential backoff and jitter. Preserve the same Idempotency-Key and identical JSON payload when retrying one logical send.

سياق الدعم

سجّل وقت الطلب والمسار ورمز حالة HTTP ومعرّف مورد SendHQ وحقول الخطأ غير السرية. لا تُدرج أبدًا مفتاح API أو كوكي الجلسة أو نص الرسالة أو قائمة المستلِمين في بلاغ الدعم.