الأخطاء

يلتزم مرقم بغلاف JSON ثابت لجميع الأخطاء:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": []
  },
  "request_id": "..."
}

رأس X-Request-Id يطابق حقل request_id.

أكواد الأخطاء الشائعة

UNAUTHORIZED — 401

• رأس المصادقة مفقود
• مفتاح API غير صالح
• فشل التحقق من Bearer token

FORBIDDEN — 403

• المصادقة ناجحة لكن الوصول مرفوض (نقاط admin، حساب موقوف، إلخ)

NOT_FOUND — 404

• القالب أو الخط أو المفتاح غير موجود

VALIDATION_ERROR — 422

• فشل التحقق من مخطط JSON
• حقول مطلوبة مفقودة في طلبات multipart
• هيكل مخطط القالب غير صالح

PAYLOAD_TOO_LARGE — 413

• حجم الطلب يتجاوز الحد الأقصى (MAX_REQUEST_MB)

RATE_LIMITED — 429

• تجاوز حد معدل الاستدعاء لمفتاح API على POST /v1/render
• يتضمن رأس Retry-After (بالثواني)

OVERLOADED — 503

• الخدمة مثقلة ورفضت الطلب قبل قراءة الـ body
• يتضمن رأس Retry-After (بالثواني)

RENDER_TIMEOUT — 408

• تجاوز الرندر الوقت المحدد RENDER_TIMEOUT_MS

REQUEST_TIMEOUT — 408

• تجاوز قراءة body الطلب الوقت المحدد BODY_READ_TIMEOUT_MS (حماية من الطلبات البطيئة)