خطاها
همهٔ خطاها ساختار یکسانی دارند و پیام فارسیِ قابل نمایش به کاربر دارند.
{
"error": "insufficient_credits",
"message": "اعتبار شما کافی نیست.",
"needed": 10,
"available": 3
}مدیریت خطا
در SDK هر خطا کلاس مخصوص خودش را دارد؛ لازم نیست رشته مقایسه کنید.
import {
InsufficientCreditsError, RateLimitError,
ConcurrencyLimitError, TierRequiredError,
} from '@aiproxy/sdk';
try {
const job = await client.jobs.run('face-swap', { target_id: id });
} catch (err) {
if (err instanceof InsufficientCreditsError) {
// به کاربر بگویید چقدر کم دارد
showTopUp(err.needed - err.available);
} else if (err instanceof RateLimitError) {
// SDK خودش تلاش مجدد میکند؛ این یعنی همهٔ تلاشها ناموفق بوده
await sleep(err.retryAfter * 1000);
} else if (err instanceof ConcurrencyLimitError) {
enqueueForLater(id);
} else if (err instanceof TierRequiredError) {
showUpgrade(err.requiredTier);
} else {
throw err;
}
}فهرست کامل
| کد | HTTP | کلاس SDK | معنی | تکرارپذیر |
|---|---|---|---|---|
insufficient_credits | 402 | InsufficientCreditsError | اعتبار کافی نیست. مقدار لازم در پاسخ آمده. | خیر |
rate_limited | 429 | RateLimitError | سقف درخواست در دقیقه پر شده. به Retry-After توجه کنید. | بله |
concurrency_limit | 429 | ConcurrencyLimitError | تعداد پردازش همزمان پر است. منتظر پایان کارهای قبلی بمانید. | بله |
tier_required | 403 | TierRequiredError | این ابزار به اشتراک بالاتری نیاز دارد. | خیر |
video_too_long | 403 | ApiError | طول ویدیو از سقف اشتراک بیشتر است. | خیر |
file_too_large | 413 | ApiError | حجم فایل از سقف اشتراک بیشتر است. | خیر |
invalid_key | 401 | AuthenticationError | کلید نامعتبر یا باطلشده است. | خیر |
forbidden_tool | 403 | AuthenticationError | این کلید به این ابزار دسترسی ندارد. | خیر |
tool_not_found | 404 | NotFoundError | ابزار وجود ندارد یا غیرفعال است. | خیر |
not_found | 404 | NotFoundError | منبع درخواستی پیدا نشد. | خیر |
invalid_input | 422 | ValidationError | ورودی نامعتبر است. هیچ اعتباری کسر نشده. | خیر |
window_exhausted | 429 | ApiError | سقف مصرف ۵ ساعت اخیر پر شده است. | بله |
service_unavailable | 503 | ServiceUnavailableError | اختلال موقت. اعتبار کسرشده خودکار بازمیگردد. | بله |
پول شما امن است. اگر پردازشی ناموفق شود، اعتبار کسرشده بهصورت خودکار و دقیقاً یک بار بازگردانده میشود — حتی اگر خطا از سمت ما باشد.
تلاش مجدد
SDK خطاهای تکرارپذیر را با فاصلهٔ فزاینده و jitter دوباره تلاش میکند. اما یک درخواست POST فقط وقتی تکرار میشود که هدرIdempotency-Keyداشته باشد — وگرنه قطعیِ شبکه پس از پذیرش کار، باعث ارسال و کسر اعتبار دوباره میشد.