Invalid Idempotency Key

invalid-idempotency-key · 400

جاء الـ header Idempotency-Key بقيمة لا تستطيع الـ API استعمالها، فلم تنفذ العملية.

كل الصفحات

كانت القيمة فارغة أو أطول من 255 حرفا. والـ errors[] يسمي الـ header بالحقل field: "Idempotency-Key".

إضافة إلى الحقول التي في كل خطأ، يضيف هذا النوع errors.

الأسباب الشائعة

  • عبئ الـ header من متغير كان فارغا في تلك اللحظة.
  • بني المفتاح من حمولة طويلة بدل أن يبنى من معرف.

كيف تصلح الطلب

  • أرسل UUID كمفتاح. فهو قصير ولا يتكرر ولا يحتاج إلى تنسيق.
  • أنشئ المفتاح مرة واحدة لكل عملية، واستعمله في كل مرة تعيد فيها المحاولة. المفتاح الذي تنشئه من جديد في كل محاولة يفسد الغرض منه.
  • احذف الـ header كله بدل أن ترسله فارغا.

مثال على الرد

json
{
  "type": "invalid-idempotency-key",
  "title": "Invalid Idempotency Key",
  "detail": "Idempotency-Key must be a non-empty string of at most 255 characters. A UUID is recommended.",
  "errors": [
    {
      "field": "Idempotency-Key",
      "message": "must be between 1 and 255 characters",
      "value": ""
    }
  ],
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/services",
  "method": "POST",
  "instance": "POST /v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/services",
  "status": 400,
  "docs": "https://ghaym.me/docs/errors/invalid-idempotency-key"
}