الأخطاء

كل خطأ من /v1 هو وثيقة RFC 9457 Problem Details مع رمز آلي ثابت code وrequest_id. تفرّع على code لا على detail.

HTTP/1.1 404 Not Found
content-type: application/problem+json; charset=utf-8
X-Request-Id: 6f5a…

{
  "type": "https://antisandbox.com/developers/docs/errors#not_found",
  "title": "Not found", "title_ar": "غير موجود",
  "status": 404, "detail": "Not found",
  "code": "not_found", "request_id": "6f5a…"
}

أخطاء التحقق تضيف errors: [{ path, message }]. نقطة الرمز (/v1/oauth/token) تتكلم RFC 6749: { error, error_description, request_id }.

الرموز

HTTP	code	متى
400	`validation_failed`	الجسم أو الاستعلام أو المسار لا يطابق المخطط (errors[] يقول أين). الحقول المجهولة مرفوضة.
400	`invalid_json`	الجسم ليس JSON.
400	`idempotency_key_required`	POST /v1/inbound-events بلا Idempotency-Key.
401	`unauthorized`	لا رمز Bearer.
401	`invalid_token`	توقيع أو خوارزمية أو iss/aud خاطئة، أو الرمز منتهٍ، أو لم يعد يطابق تطبيقه.
401	`app_inactive`	التطبيق معلّق أو ملغى.
401	`ip_not_allowed`	عنوان المتصل خارج القائمة المسموحة.
403	`browser_credentials_refused`	الطلب يحمل ترويسة Origin.
403	`insufficient_scope`	الرمز لا يحمل أي نطاق تقبله العملية (WWW-Authenticate يسمّيها).
404	`not_found`	لا مسار كهذا، أو لا كائن كهذا في هذه المنظمة.
409	`conflict`	تكرار (هوية قناة موجودة) أو حالة ترفض التغيير.
409	`idempotency_key_reused`	نفس المفتاح مع طلب مختلف.
409	`idempotency_in_progress`	الطلب الأول بنفس المفتاح ما زال يعمل (Retry-After: 1).
413	`payload_too_large`	الجسم أكبر من 1 MB.
415	`unsupported_media_type`	كتابة بلا content-type: application/json.
422	`sandbox_unavailable`	تطبيق سندبوكس أرسل حدثاً لمنظمة حية.
429	`rate_limited`	انظر Retry-After وX-RateLimit-*.
500	`internal_error`	خطؤنا — اذكر request_id.
503	`signing_key_unavailable`	توقيع الرموز غير مهيأ على الخادم.

إعادة المحاولة

429: انتظر Retry-After. 409 idempotency_in_progress: أعد بعد ثانية بنفس المفتاح. 5xx: أعد بنفس Idempotency-Key (المحاولة الفاشلة لا تُخزَّن فتُنفَّذ الإعادة). غير ذلك: أصلح الطلب.