خطاها
قالب خطا و کدهای پایدار.
همه خطاها قالب یکسانی دارند. برنامه خود را بر اساس code بنویسید؛ متن message برای نمایش به کاربر است و ممکن است تغییر کند.
json
{
"error": {
"code": "validation_error",
"message": "اطلاعات ارسالی معتبر نیست.",
"request_id": "req_3f2a9c…",
"details": [{ "field": "callback_url", "message": "Invalid URL" }]
}
}هر پاسخ (موفق یا ناموفق) هدر X-Request-Id دارد. هنگام تماس با پشتیبانی این شناسه را اعلام کنید. می‌توانید شناسه خودتان را هم در همین هدر بفرستید (۸ تا ۱۲۸ کاراکتر).
کدها
| code | HTTP | پیام پیش‌فرض |
|---|---|---|
| validation_error | 400 | اطلاعات ارسالی معتبر نیست. |
| bad_request | 400 | درخواست نامعتبر است. |
| invalid_api_key | 401 | کلید API نامعتبر است. |
| forbidden | 403 | دسترسی به این بخش برای شما مجاز نیست. |
| ip_blocked | 403 | دسترسی از این آدرس IP مسدود است. |
| not_found | 404 | مورد درخواستی یافت نشد. |
| conflict | 409 | این عملیات با وضعیت فعلی در تعارض است. |
| already_exists | 409 | این مورد قبلاً ثبت شده است. |
| idempotency_key_reused | 422 | کلید یکتایی با درخواست متفاوتی استفاده شده است. |
| idempotency_in_progress | 409 | درخواست مشابهی در حال پردازش است. |
| rate_limited | 429 | تعداد درخواست‌ها بیش از حد مجاز است. کمی بعد تلاش کنید. |
| module_disabled | 403 | این قابلیت در حال حاضر فعال نیست. |
| internal_error | 500 | خطای داخلی رخ داد. لطفاً دوباره تلاش کنید. |
| service_unavailable | 503 | سرویس موقتاً در دسترس نیست. |
| amount_out_of_range | 400 | مبلغ خارج از محدوده مجاز است. |
| gateway_inactive | 403 | درگاه پرداخت فعال نیست. |
| callback_domain_mismatch | 400 | آدرس بازگشت با دامنه ثبت‌شده درگاه مطابقت ندارد. |
| payment_not_found | 404 | پرداخت یافت نشد. |
| payment_expired | 410 | مهلت پرداخت به پایان رسیده است. |
| payment_invalid_state | 409 | وضعیت پرداخت اجازه این عملیات را نمی‌دهد. |
| payment_amount_mismatch | 400 | مبلغ با مبلغ پرداخت مطابقت ندارد. |
| no_provider_available | 503 | در حال حاضر هیچ درگاه بانکی در دسترس نیست. |
| provider_error | 502 | ارتباط با بانک با خطا مواجه شد. |
| provider_timeout | 504 | پاسخ بانک در زمان مقرر دریافت نشد. |
| capability_not_supported | 422 | این عملیات توسط درگاه بانکی مربوطه پشتیبانی نمی‌شود. |
| refund_exceeds_amount | 422 | مبلغ استرداد بیشتر از مبلغ قابل استرداد است. |
| insufficient_balance | 422 | موجودی کافی نیست. |
| fraud_blocked | 403 | این تراکنش به دلایل امنیتی مسدود شد. |
| live_mode_not_enabled | 403 | حالت عملیاتی برای این درگاه فعال نشده است. |
نکات مهم
409 payment_invalid_state: وضعیت فعلی پرداخت اجازه این عملیات را نمی‌دهد (مثلاً برگشت پرداخت تسویه‌شده). وضعیت را استعلام کنید.403 module_disabled: این قابلیت برای حساب شما یا در کل سامانه فعال نیست.422 insufficient_balance: موجودی شما برای استرداد کافی نیست.504 provider_timeout: پاسخ بانک نرسید؛ عملیات به‌صورت خودکار پیگیری می‌شود. استرداد در این حالت به‌جای خطا پاسخ202می‌گیرد.