الأخطاء وإعادة المحاولة

تنطبق الأدلة المشتركة على واجهتي تحويل الصور إلى نصوص وجداول. راجع مرجع كل واجهة لمعرفة المدخلات والصيغ والأخطاء الخاصة بها.

استجابات الأخطاء

مثال لاستجابة خطأ JSON:

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "error": {
    "code": "insufficient_balance",
    "message": "Recognition did not complete",
    "required_reservation_usd": "0.011288000"
  }
}

رموز حالة HTTP

HTTP	error.code
400	invalid_request, invalid_idempotency_key, invalid_image
401	unauthorized
402	insufficient_balance
403	account_unavailable
405	invalid_request
409	idempotency_conflict, request_in_progress
413	image_too_large, input_limit_exceeded
415	unsupported_media_type
422	recognition_blocked
429	rate_limit_exceeded, concurrency_limit_exceeded
502	recognition_failed, output_truncated, empty_result, invalid_usage
503	service_unavailable, settlement_pending, export_failed
504	request_timeout

HTTP	السبب	الإجراء
400 / 413 / 415	طلب أو حجم صورة أو نوع وسائط غير صالح	صحح الملف أو قلل حجمه
405	طريقة HTTP غير صحيحة	استخدم POST
401	مفتاح API مفقود أو غير صالح	تحقق من مفتاح Bearer
403	الحساب غير متاح	أكمل التحقق أو عالج تقييد الحساب
402	الرصيد المتاح غير كاف	اشحن الرصيد وراجع error.required_reservation_usd وقواعد الرصيد والحجز
409	تعارض معرّف العملية أو استمرار معالجتها	عند request_in_progress احتفظ بالمعرّف والصورة ثم انتظر وأعد المحاولة؛ وعند التعارض صحح معرّف العملية
429	تجاوز حد الطلبات أو التزامن	انتظر وفق Retry-After
422 / 502 المؤكد	إخفاق التعرف المؤكد	لا تُفرض رسوم للتعرف؛ تحقق من الخطأ
503 / 504 / حالة غير مؤكدة	عدم يقين الخدمة أو التسوية أو المهلة	لا تفترض عدم الخصم؛ أعد المحاولة باستخدام Idempotency-Key والصورة الأصليين

تعود الأخطاء بصيغة JSON وتحتوي request_id وerror.code وerror.message. تستخدم جميع الاستجابات Cache-Control: no-store؛ التعرف غير متدفق، وتستخدم الاستجابة الناجحة الصيغة المحددة بينما تبقى الأخطاء JSON. احتفظ بـ X-Request-Id عند التواصل مع الدعم.

منع التكرار

Idempotency-Key هو معرّف العملية: من 16 إلى 128 حرف ASCII أو رقماً أو . _ : -. استخدم معرّفاً فريداً جديداً لكل صورة جديدة، واحتفظ بالمعرّف والبايتات الأصلية وMIME عند الإعادة. النطاق هو الحساب حتى عند تغيير المفتاح. خلال 24 ساعة من القبول تعيد العملية المكتملة request_id والنتيجة والتكلفة الأصلية مع Idempotency-Replayed: true دون توليد أو خصم جديد.

استخدم Idempotency-Key مختلفاً لكل عملية أو نقطة وصول جديدة. تؤدي مشاركته بين واجهتي النص والجداول إلى 409 idempotency_conflict. عند تغيير صيغة العملية نفسها أعد استخدام المفتاح والصورة الأصليين.

استراتيجية إعادة المحاولة

عند خطأ شبكة أو request_in_progress أو settlement_pending، احتفظ بالمعرّف والصورة وانتظر Retry-After ثانية ثم أعد المحاولة. لا تنشئ عملية أخرى ما دام التسوية غير مؤكدة. الإخفاقات النهائية المحفوظة تعيد الخطأ نفسه؛ استخدم معرّفاً جديداً فقط لبدء مقصود بعد تأكيد الفشل. بعد 24 ساعة قد ينشئ المعرّف عملية مدفوعة جديدة، ويظل الاسترداد غير المكتمل مانعاً لإعادة الاستخدام.

أمان الفوترة

إخفاق التعرف المؤكد لا يُحاسب، لكن فقدان الاستجابة أو settlement_pending قد يعني إتمام الخصم أو استمرار الحجز. لا تبدأ عملية بمعرّف Idempotency-Key جديد أثناء عدم وضوح النتيجة؛ أعد المحاولة بنفس المعرّف والصورة، واحتفظ بـ X-Request-Id للدعم.