OpenAI invalid_api_key: معناه وسببه وحله

أين يحدث الخلل عادةً؟

غالباً يكون المفتاح صحيحاً في المصدر لكنه يصل إلى التطبيق بصورة مختلفة: نسخة ناقصة، أو علامات اقتباس دخلت في قيمة .env، أو سطر جديد في سرّ CI، أو مفتاح بيئة التجهيز مستخدم في الإنتاج.

العائلة الأخرى إدارية. المفتاح أُلغي أو دُوِّر، أو يعود لمشروع غير الذي تستدعيه، أو أن IP خادمك ليس على القائمة المسموح بها التي تفرضها مؤسستك. كل واحدة من هذه تُرجع 401 نفسه — ولهذا تُشخّص بالطبقة لا بالتخمين.

الاستجابة

HTTP/1.1 401 Unauthorized

{
  "error": {
    "message": "Incorrect API key provided: sk-abc***. You can find your API key in your dashboard.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

ذلك الجسم تمثيلي، لا نسخة حرفية. الجزء المُقنَّع يردّد ما أرسلته: إن لم يطابق المفتاح الذي قصدت تحميله، فالبيئة هي العلّة. ويجدر بك أن تعرف: 401 قد يعني أيضاً غياب عضوية المؤسسة أو IP خارج القائمة المسموح بها، و403 الذي يقول "Country, region, or territory not supported" هو جغرافيا، لا مصادقة.

تشخيص سريع

# 1. Is the env var what you think it is?
echo "len=${#OPENAI_API_KEY} head=${OPENAI_API_KEY:0:4} tail=${OPENAI_API_KEY: -4}"

# 2. Does the key itself pass auth?
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

اقرأ الصدى أولاً. طول صفر يعني أن المتغيّر لم يُحمَّل قط. ذيلٌ يُظهر علامة اقتباس أو حرفاً غريباً يعني أن ملف البيئة مشوّه. إن بدا الصدى صحيحاً وأرجع الـ curl قائمة نماذج، فالمفتاح يعمل وتطبيقك يحمّل شيئاً آخر، عادةً عملية قديمة. وإن أرجع الـ curl خطأ 401 على مفتاح سُكَّ قبل دقائق، فكُفّ عن التحديق في النص وافحص نطاق المشروع وعضوية المؤسسة والقائمة المسموح بها.

امنع تكراره

احتفظ بالمفاتيح في مدير أسرار، وأنشئ مفتاحاً مستقلاً لكل بيئة حتى يبقى أثر أي تسريب محدوداً. وشغّل فحص مصادقة بسيطاً عند بدء التطبيق، كي يفشل النشر مبكراً إذا كان المفتاح ملغى أو غير صحيح، بدلاً من أن يظهر الخطأ لأول مستخدم.