الأخطاء والحدود

الأخطاء التي ينتجها GetVibe على /v1/* لها غلاف JSON يحتوي على error.message وerror.type وerror.code. لا تعتمد على نص الرسالة أو ترويسات خدمات الطرف الثالث كعقد.

{
  "error": {
    "message": "insufficient balance",
    "type": "insufficient_quota",
    "code": 402,
    "request_id": "8d4b6b3a-..."
  }
}

يتضمن كل خطأ في الطلب رمز error.code ثابتًا من الجدول أدناه، وerror.param يحدد الحقل المعني (وتكون قيمته null عندما لا يحدد النموذج حقلًا)، ورابطًا إلى الصف المطابق في نهاية error.message — إذ لا يعرض Codex وغيره من أدوات CLI سوى الرسالة، لذا يُدرج الرابط فيها.

البث البطيء (stream: true) يتلقّى تعليقات 200 و: pv-keepalive بعد 5 ثوانٍ من الصمت حتى لا تبدو الاتصال ميتًا؛ أما الطلب الطويل غير المتدفق فيتلقّى 200 ومسافات بيضاء بعد أول رمز له. من ذلك الحين لا يمكن أن تتغير الحالة، ويصل الخطأ في متن الاستجابة. إذا كان عميلك يتحول عند خطأ HTTP إلى مورد آخر، فأرسل x-pv-honest-errors: 1 (أو اطلب من الدعم تمكينه للحساب): عندئذٍ لا يوجد keepalive ولا 200 مبكر قبل أول بايت من الاستجابة، وكل فشل هو حالة HTTP عادية مع متن JSON. الثمن هو مقبس صامت حتى أول رمز؛ ويجب أن تغطي مهلة ترويستك هذه الفترة.

الخطأ الذي يقع بعد بدء الاستجابة هو حدث نهائي واحد: في حال الدردشة event: error مع {"error":{message,type,code,status},"choices":[{"finish_reason":"error"}]} يتبعه data: [DONE]؛ وفي /v1/responses يأتي event: response.failed حاملًا نفس error؛ وفي /v1/messages يأتي event: error الخاص بـ Anthropic. يمثل code السبب البرمجي، وstatus حالة HTTP التي كان الخطأ سيعيدها قبل بدء الاستجابة.

يعتمد كلا الحدّين على الرصيد الحالي للحساب، وينطبقان على جميع مفاتيح API التابعة له مجتمعةً. يُعاد احتساب الفئة تلقائيًا: عند إضافة رصيد يرتفع الحد؛ وعند انخفاض الرصيد دون عتبة معينة تنخفض الفئة. لا يوجد حد لعدد الرموز في الدقيقة (TPM).

بالنسبة إلى استجابة قابلة لإعادة المحاولة استخدم أولاً Retry-After إن كانت موجودة. وبدون الترويسة، لا تعامل أي 429 أو 503 على أنها قابلة لإعادة المحاولة تلقائياً: تحقق من حالة HTTP ومن error.type العام، وأصلح السبب غير القابل لإعادة المحاولة، واستخدم تراجعاً محدوداً فقط للأخطاء العابرة.

import time, requests

def call_with_retry(url, headers, payload, max_retries=5):
    for attempt in range(max_retries):
        r = requests.post(url, headers=headers, json=payload)
        if r.status_code == 429:
            # honor Retry-After, otherwise exponential backoff
            wait = int(r.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        return r
    return r