خطاها

درخواستی که ناموفق باشد کد وضعیت غیر 2xx و یک شیء error برمی‌گرداند:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "amount must be greater than or equal to 10000",
    "param": "amount",
    "doc_url": "https://bezanbecard.com/docs/errors#amount_too_small",
    "request_id": "req_…"
  }
}

نوع‌ها و کدهای وضعیت

کتابخانه‌های رسمی برای هر نوع یک کلاس استثنا دارند (کتابخانه‌ها را ببینید).

کدهای درخواست

parameter_missing

یک پارامتر الزامی نیامده است. param نامش را می‌گوید.

parameter_unknown

بدنه پارامتری دارد که این مسیر نمی‌گیرد. املایش را با مرجع API مقایسه کنید.

parameter_invalid

مقدار یک پارامتر پذیرفته نیست، یا پارامتر expand[]، created یا نشانگر صفحه‌بندی شکل درستی ندارد.

parameter_invalid_integer

پارامتر باید عدد صحیح باشد، مثل limit (۱ تا ۱۰۰) یا مبلغ به ریال.

parameter_invalid_empty

پارامتری که مقدار لازم دارد به‌صورت رشتهٔ خالی فرستاده شده است.

amount_too_small

مبلغ کمتر از ۱۰٬۰۰۰ ریال است.

amount_too_large

مبلغ بیشتر از ۲٬۰۰۰٬۰۰۰٬۰۰۰ ریال است.

json_invalid

بدنه JSON معتبری نیست.

request_too_large

بدنه بزرگ‌تر از ۱۰۰ کیلوبایت است.

url_invalid

هیچ مسیری با این نشانی و متد وجود ندارد.

not_implemented

این مسیر یا قابلیت هنوز در دسترس نیست.

resource_missing

شیئی با این شناسه در این حساب و حالت نیست (شناسهٔ آزمایشی با کلید واقعی هم پیدا نمی‌شود)، یا نشانگر صفحه‌بندی به هیچ شیئی از فهرست اشاره نمی‌کند.

resource_already_exists

شیئی با همین مقدارهای یکتا از قبل وجود دارد.

resource_conflict

شیء هم‌زمان با درخواست دیگری تغییر کرده است. دوباره بخوانید و دوباره بفرستید.

api_version_invalid

هدر Bezanbecard-Version نسخه‌ای را نام می‌برد که وجود ندارد.

کدهای احراز هویت و دسترسی

api_key_missing

کلیدی فرستاده نشده است. Authorization: Bearer sk_… را بفرستید.

api_key_invalid

کلید مال بزن به کارت نیست یا اشتباه تایپ شده است.

api_key_revoked

کلید باطل شده است. کلید تازه بسازید.

api_key_expired

کلید تعویض شده و زمان هم‌پوشانی‌اش گذشته است. از کلید تازه استفاده کنید.

permission_denied

کلید محدود دسترسی لازم برای این درخواست را ندارد. دسترسی‌هایش را ویرایش کنید یا کلید دیگری به کار ببرید.

secret_key_required

کلید عمومی فرستاده شده است. همهٔ مسیرها کلید مخفی یا محدود می‌خواهند.

test_mode_only

این مسیر، مثل POST /v1/test_helpers/deposits، فقط با کلید آزمایشی کار می‌کند.

account_suspended

حساب تعلیق شده و کلیدهایش رد می‌شوند. با پشتیبانی تماس بگیرید.

account_restricted

حساب محدود شده است (به دست اپراتور یا برای صورت‌حساب پرداخت‌نشده): پرداخت واقعی ساخته نمی‌شود و بقیهٔ کارها انجام می‌شود. صورت‌حساب را بپردازید یا با پشتیبانی تماس بگیرید.

billing_limit_reached

به سقف طرح برای این منبع (لینک پرداخت واقعی، کارت و حساب، گوشی یا عضو تیم) رسیده‌اید. طرح را ارتقا دهید یا یکی را بایگانی کنید.

کدهای درخواست تکرارپذیر

idempotency_key_invalid

هدر Idempotency-Key خالی یا بلندتر از ۲۵۵ نویسه است.

idempotency_key_reused

این کلید در ۲۴ ساعت گذشته با درخواست دیگری به کار رفته است. برای عملیات تازه کلید تازه بسازید.

idempotency_key_in_use

درخواست اول با این کلید هنوز در جریان است. کمی بعد دوباره بفرستید.

rate_limit

درخواست‌های این کلید زیاد است: ۱۰۰ در ثانیه در حالت واقعی و ۲۵ در حالت آزمایشی. بارگذاری رسید هم ممکن است وقتی سرور سرگرم خواندن فایل‌های دیگر است چند ثانیه منتظر بماند. به اندازهٔ ثانیه‌های Retry-After صبر کنید.

کدهای پرداخت

payment_already_changed

پرداخت هم‌زمان با درخواست شما تغییر کرده است (واریزی رسیده، هم‌تیمی‌تان کاری کرده)، یا تغییر دیگری روی همین پرداخت هنوز در جریان بوده است، یا (در resolve_overpayment) اعتباری برای مشتری با مبلغی غیر از مبلغ اضافه‌پرداخت هنوز ثبت نشده و یکی از اعضای تیم باید آن را رسیدگی کند. در حالت دوم هیچ کاری انجام نشده، پس تکرار درخواست با همان Idempotency-Key اجرا می‌شود؛ در غیر این صورت پرداخت را دوباره بخوانید و دوباره تصمیم بگیرید.

payment_action_unavailable

این کار برای پرداخت در وضعیت فعلی‌اش ممکن نیست، مثل تأیید پرداختی که موفق شده است.

payment_not_open

پرداخت بسته شده و دیگر نمی‌شود ویرایشش کرد یا مبلغ تکمیلی خواست.

payment_amount_unavailable

فعلاً هیچ مبلغ یکتای آزادی روی این کارت نیست (پرداخت‌های باز زیادی تقریباً همین مبلغ را می‌خواهند). دوباره بفرستید یا card دیگری بدهید.

payment_amount_invalid

مبلغ بیرون از سقف و کف پرداخت است.

payment_expiry_invalid

expires_in بیرون از بازهٔ ۳۰۰ تا ۸۶٬۴۰۰ ثانیه است.

payment_card_invalid

card کارت یا حساب فعالی از این حساب و حالت نیست که یکی از روش‌های پرداخت روشن شما را بپذیرد.

payment_customer_invalid

customer مشتری این حساب و حالت نیست.

payment_customer_required

بستن بیش‌واریز با credited به پرداختی نیاز دارد که مال یک مشتری باشد.

payment_deposit_invalid

deposit واریز این حساب و حالت نیست.

payment_deposit_not_attached

واریزی که می‌خواهید جدا کنید به این پرداخت وصل نیست.

payment_overpayment_not_pending

پرداخت بیش‌واریز بازی برای بستن ندارد.

payment_metadata_invalid

metadata از یکی از حدها گذشته است: حداکثر ۵۰ کلید، کلید تا ۴۰ نویسه، مقدار تا ۵۰۰ نویسه، فقط متن.

card_none_available

هیچ کارت یا حساب فعالی نمی‌تواند این پرداخت را بگیرد: در این حالت هیچ‌کدام یکی از روش‌های پرداخت روشن را نمی‌پذیرد، یا همه به سقف روزانه رسیده‌اند. کارت یا حساب اضافه کنید، روش پرداخت دیگری را روشن کنید یا سقف را بالا ببرید.

کدهای واریز

deposit_already_matched

واریز به پرداختی وصل است. اول آن را از آنجا جدا کنید.

deposit_already_changed

واریز هم‌زمان با درخواست شما تغییر کرده است. دوباره بخوانید و دوباره بفرستید.

deposit_given_back

پول این واریز به مشتری برگردانده شده (بازپرداخت یا اعتبار) و دوباره به این پرداخت وصل نمی‌شود. اگر مشتری دوباره پرداخت می‌کند، پرداخت تازه‌ای بسازید.

deposit_receipt_partial

یک رسید تأییدشدهٔ این پرداخت بخشی از همین انتقال را پوشش داده است. به‌جای وصل کردن واریز بانکی، همان رسید را اصلاح کنید؛ وگرنه یک انتقال دو بار شمرده می‌شود.

deposit_not_matched

این کار به واریز وصل‌شده نیاز دارد.

deposit_card_required

کارتی برای این واریز نیست: card را بفرستید یا یک کارت آزمایشی فعال اضافه کنید.

deposit_card_invalid

card کارت این حساب و حالت نیست.

deposit_amount_required

amount را بفرستید، یا paymentی که هنوز منتظر واریز است.

deposit_payment_invalid

payment پرداخت این حساب و حالت نیست.

کدهای رسید

receipt_action_unavailable

این تصمیم به وضعیت فعلی رسید نمی‌خورد: پیش‌تر تأیید، رد یا جایگزین شده است. دوباره بخوانیدش.

receipt_already_changed

رسید در همان مدتی که این درخواست اجرا می‌شد تغییر کرد و چیزی تأیید نشد. رسید را دوباره بخوانید و بر اساس آنچه الان نشان می‌دهد دوباره تصمیم بگیرید. در داشبورد، پنجرهٔ تأیید هم وقتی آنچه نشان داده بود دیگر درست نیست همین کد را می‌گیرد (گفته بود تأیید پولی اضافه نمی‌کند یا پرداختی را دوباره باز نمی‌کند، یا رقم بیش‌واریزی را نشان داده بود، و در این فاصله تصمیم هم‌تیمی، جدا کردن یک واریز یا لغو پرداخت آن را عوض کرده است)؛ آن‌وقت پنجره رقم‌های تازه را نشان می‌دهد. اگر هم‌تیمی‌ای زودتر دربارهٔ همان رسید تصمیم گرفته باشد، به‌جای این receipt_action_unavailable می‌گیرید.

receipt_amount_required

هیچ چیز نمی‌گوید چه مبلغی تأیید شود: رسید مبلغ ندارد و پرداخت هم مبلغی انتظار ندارد، یا بیش‌واریزِ رسیدی بی‌مبلغ را (overpay: true) تأیید می‌کنید. amount را بفرستید.

receipt_amount_mismatch

واریز پیامکی بانک برای این انتقال مبلغ دیگری دارد. مبلغ بانک را تأیید کنید، یا اول آن واریز را جدا کنید. وصل کردن واریزی به رسیدی که روی واریز رسید ایستاده هم، وقتی دو مبلغ با هم فرق دارند، همین را می‌گیرد (param برابر deposit است): جایگزینی هیچ‌وقت پول را جابه‌جا نمی‌کند.

receipt_deposit_invalid

deposit هیچ واریز بانکی‌ای روی کارت یا حساب این پرداخت نیست.

receipt_deposit_unavailable

این واریز به پرداخت دیگری وصل است، یا رسید دیگری روی آن ایستاده یا با آن تطبیق خورده است.

receipt_deposit_taken

دیگر فرستاده نمی‌شود: پاسخی قدیمی برای واریزی که پشتوانهٔ رسید تأییدشدهٔ دیگری بود. آن را مثل receipt_deposit_unavailable بخوانید.

receipt_payment_settled

تأیید بیشتر از مبلغی که پرداخت هنوز لازم دارد ثبت می‌کند و بیش‌واریز می‌سازد (روی پرداختی که پیش‌تر موفق شده، همه آن). برای پذیرفتن بیش‌واریز overpay: true را بفرستید. param برابر overpay است و /v1 مبلغی همراه آن نمی‌فرستد.

receipt_payment_refunded

پرداخت لغو یا منقضی شده و پولش به مشتری برگشته است (بازپرداخت یا اعتبار)، پس هیچ رسیدی روی آن تأیید نمی‌شود. برای واریز تازه، پرداخت تازه‌ای بسازید.

receipt_overpayment_resolved

بیش‌واریز این پرداخت پیش‌تر تعیین تکلیف شده (بازپرداخت، اعتبار یا نگه‌داشتن) و این تأیید آن را بیش از آن بیش‌واریز می‌کند. حداکثر به اندازه باقی‌مانده پرداخت تأیید کنید یا رسید را رد کنید. param برابر amount است.

receipt_channel_unavailable

پرداخت این نوع انتقال را نمی‌پذیرد، مثلاً paya روی پرداختی که فقط کارت‌به‌کارت می‌پذیرد.

receipt_field_required

فیلدی که پرداخت لازم دارد نیامده است؛ param نامش را می‌گوید، مثلاً channel روی پرداختی که فقط انتقال بانکی می‌پذیرد.

receipt_payment_invalid

فیلتر payment هیچ پرداختی از این حساب و حالت نیست.

کدهای فایل رسید

file_too_many

هر رسید حداکثر ۳ فایل می‌گیرد.

file_too_large

فایلی بزرگ‌تر از ۱۰ مگابایت است. کد وضعیت 413 است.

file_invalid_type

فایلی عکس JPEG، PNG، WebP یا HEIC یا PDF نیست. نوع فایل از روی محتوایش خوانده می‌شود، هرگز از روی نامش.

file_invalid_upload

بدنهٔ multipart خوانده نشد. فایل‌ها را در فیلد files بفرستید.

کدهای لینک پرداخت

link_amount_required

لینک با مبلغ ثابت amount[value] لازم دارد.

link_amount_invalid

مبلغ، یکی از حدها یا یکی از مبلغ‌های پیشنهادی بیرون از سقف و کف پرداخت است، یا مبلغ پیشنهادی بیرون از بازه است.

link_amount_range_invalid

amount[min] از amount[max] بیشتر است.

link_after_url_required

after_completion[type] برابر redirect است ولی after_completion[url] نیامده است.

link_limits_invalid

max_uses باید عدد صحیح مثبت باشد.

کدهای مشتری

customer_phone_taken

مشتری دیگری در همین حالت همین شمارهٔ موبایل را دارد. همان مشتری را به کار ببرید.

customer_phone_invalid

شماره، شمارهٔ موبایل ایرانی نیست.

customer_payments_open

مشتری پرداخت باز دارد؛ پیش از حذف، آن‌ها را تمام یا لغو کنید.

کدهای نقطهٔ دریافت وب‌هوک

webhook_url_invalid

نشانی معتبر نیست، یا برای نقطهٔ دریافت واقعی https نیست.

webhook_destination_private

نشانی به آدرس خصوصی یا loopback می‌رسد.

webhook_events_required

enabled_events خالی است.

کدهای اتصال

connect_code_invalid

کد اتصال ناشناخته است، قبلاً استفاده شده یا منقضی شده است. اتصال را از افزونه دوباره شروع کنید.