رموز خطأ SpeakNotes API

كل فشل يعيد نفس غلاف JSON: رمز ثابت، رسالة مفهومة للبشر، رابط لهذه الصفحة، والحقول التي تسببت في الخطأ إن وجدت.

الشكل

لا تعود الأخطاء أبداً بتنسيق HTML. الكود مستقر وآمن للاعتماد عليه في البرمجة؛ بينما يمكن أن تتغير الرسالة في أي وقت.

HTTP/1.1 402 Payment Required
X-Request-Id: 0f0a3f2c-6f1e-4a5e-9f1b-9d0b5a2c7e11

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This operation costs 14 credits and the account has 3 left.",
    "doc_url": "https://speaknotes.io/developers/errors#insufficient_credits",
    "request_id": "0f0a3f2c-6f1e-4a5e-9f1b-9d0b5a2c7e11"
  }
}

الأكواد

invalid_request400
The request was malformed or failed validation.
invalid_token401
The credential is missing, malformed, expired, or revoked.
insufficient_scope403
The credential is valid but lacks the scope this operation needs.
not_found404
The requested resource does not exist.
method_not_allowed405
That HTTP method is not supported on this path.
conflict409
The request conflicts with the current state of the resource.
payload_too_large413
The uploaded file exceeds the size limit.
unsupported_media_type415
The file format is not supported.
insufficient_credits402
The account has no credits left for this operation.
rate_limited429
Too many requests. Retry after the interval in the Retry-After header.
upstream_failure502
A provider SpeakNotes depends on failed.
content_policy422
The content was refused by the AI content policy.
internal_error500
SpeakNotes failed to process the request.

ما الذي يجب إعادة محاولته

أعد محاولة rate_limited بعد الفاصل الزمني المذكور في Retry-After، وأعد محاولة upstream_failure مرة أو مرتين مع استخدام التراجع (backoff). لا تقم أبداً بإعادة محاولة invalid_request أو insufficient_scope أو content_policy دون تغيير: فهي ستفشل بنفس الطريقة في كل مرة.

معرفات الطلب

تحمل كل استجابة ترويسة X-Request-Id، وتكررها نصوص الأخطاء. قم بتزويدها للدعم الفني لتحديد سبب الفشل بدقة.