Алдааны кодууд

channel-api нь стандарт HTTP статус кодуудыг ашигладаг. Энэ хуудас бүх алдааны код, түгээмэл шалтгаан, яаж засахыг нэг дор цуглуулсан болно. Идэвхтэй интеграцлаж буй бол эдгээр кодыг кодондоо тусгайлан барьж (handle) сайжруулсан туршлага үзүүлэхийг зөвлөнө.

Нэгдсэн хүснэгт

400 — Bad Request

Хүсэлтийн бүтэц эсвэл параметр буруу үед буцна. channel-api нь NestJS ValidationPipe-ийг whitelist + forbidNonWhitelisted тохиргоотойгоор ашигладаг тул хүсэлтийн биед үл мэдэгдэх эсвэл буруу нэртэй талбар оруулбал шууд 400 авна.

Түгээмэл шалтгаанууд:

• Хүсэлтийн биед тодорхойлогдоогүй (нэмэлт) талбар дамжуулсан.
• Талбарын төрөл буруу (жишээ нь amount дээр тоо биш текст дамжуулсан).
• Буруу форматтай UUID — GET /invoices/{id}, GET /payments/{id}, DELETE /payments/{id} зэрэгт id нь хүчинтэй UUID байх ёстой.
• GET /invoices дээр шүүлтүүр буруу: ttd, vehicle, taxRef-ээс яг нэгийг дамжуулна. Хоосон үлдээх эсвэл хоёр болон түүнээс олныг зэрэг дамжуулбал 400.

Яаж засах:

• Хүсэлтийн биеэс баримтад заагдаагүй талбаруудыг ав. Төлбөр болон Нэхэмжлэл хуудаснаас зөвшөөрөгдсөн талбаруудыг шалга.
• id талбарт жинхэнэ UUID (жишээ нь GET /invoices хариунаас авсан id) дамжуулж байгаа эсэхээ шалга.
• GET /invoices дуудахдаа гурван шүүлтүүрээс яг нэгийг л өг:

# Зөв: яг нэг шүүлтүүр
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://sandbox-tts.qpay.mn/api/v1/invoices?ttd=1234567"

# Буруу: хоёр шүүлтүүр зэрэг → 400
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://sandbox-tts.qpay.mn/api/v1/invoices?ttd=1234567&vehicle=1234ABC"

401 — Unauthorized

X-API-Key header байхгүй эсвэл буруу үед буцна.

Түгээмэл шалтгаанууд:

• X-API-Key header огт дамжуулаагүй.
• API key буруу бичигдсэн, эсвэл нэг орчны key-г өөр орчинд ашигласан (sandbox key-г production-д гэх мэт).

Яаж засах:

• Бүх хүсэлтэд X-API-Key header нэмсэн эсэхээ шалга:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://sandbox-tts.qpay.mn/api/v1/reports/summary"

• Орчин бүрд тус тусдаа key байдаг тул зөв key-г зөв Base URL-тэй хослуулсан эсэхээ нягтал.

403 — Forbidden

Key хүчинтэй боловч тухайн партнёр идэвхгүй болсон үед буцна.

Түгээмэл шалтгаанууд:

• Партнёрийн бүртгэл түр зогсоосон эсвэл идэвхгүй болгосон.

Яаж засах:

• Энэ нь хүсэлтийн бус, бүртгэлийн төлвийн асуудал. gov-pay-тэй холбогдож партнёрийн бүртгэлээ идэвхжүүлэх шаардлагатай.

404 — Not Found

Хүссэн нэхэмжлэл эсвэл төлбөр олдсонгүй.

Түгээмэл шалтгаанууд:

• Байхгүй эсвэл устгагдсан id-аар хандсан.
• GET /invoices/ref/{refNum} дээр төрийн системд тухайн refNum-аар нэхэмжлэл олдоогүй.
• GET /invoices/{id}/refresh буюу GET /invoices/{id} дээр DB-д тухайн нэхэмжлэл байхгүй.

Яаж засах:

• Эхлээд GET /invoices-аар нэхэмжлэл хайж, буцаж ирсэн id-г дараагийн дуудалтад ашигла.
• refNum зөв эсэхийг нягтал. UUID формат буруу бол 404 биш 400 буцдаг тул кодоо ялгаатай барь.

422 — Unprocessable Entity (төлбөр амжилтгүй)

POST /payments дээр хүсэлт зөв боловч төрийн систем төлбөрийг боловсруулж чадаагүй үед буцна. Хариу бие нь success: false-тэй, шалтгааны мессеж болон холбогдох refNum-тэй ирнэ.

Жишээ хариу:

{
  "success": false,
  "refNum": "2024010112345",
  "message": "Payment could not be processed"
}

Түгээмэл шалтгаанууд:

• Нэхэмжлэл аль хэдийн төлөгдсөн (paid) эсвэл цуцлагдсан (canceled).
• Дүн (amount) нэхэмжлэлийн үлдэгдэлтэй таарахгүй.
• Төрийн систем тухайн нэхэмжлэлийг тухайн агшинд хүлээж аваагүй.

Яаж засах:

• Төлбөр хийхээс өмнө нэхэмжлэлийн статусыг GET /invoices/{id}-аар шалга (open эсэх).
• amount дамжуулж байгаа бол нэхэмжлэлийн дүнтэй таарч буй эсэхээ нягтал. Бүтэн дүнг төлөх бол amount-г огт дамжуулахгүй байж болно.
• message, refNum-г лог-доо хадгалж, дэмжлэг хүсэх үед ашигла.

429 — Too Many Requests

API key тус бүрд тогтоосон rate limit-ийг хэтэрсэн үед буцна. Хязгаар (Redis дээр тоологддог):

• 5 хүсэлт / секунд
• 60 хүсэлт / минут
• 1000 хүсэлт / цаг

Яаж засах:

• Хүсэлтийн давтамжаа багасга, эсвэл хүсэлтүүдийн хооронд завсарла.
• 429 авсан үед exponential backoff-той дахин оролдлого (retry) хийж, шууд давтан цохихоос зайлсхий.
• Олон нэхэмжлэлийг шалгах бол боломжтой газар үр дүнг кэшэл (жишээ нь GET /invoices/{id} нь DB cache-ээс уншдаг тул refresh-аас хямд).

5xx — Server / Upstream алдаа

Серверийн дотоод алдаа, эсвэл upstream төрийн системийн алдаа.

Чухал: Төрийн системийн дотоод алдааны дэлгэрэнгүй клиентэд задрахгүй — ерөнхий мессеж буцах бөгөөд бодит шалтгаан нь дотоод лог-д бичигддэг.

Яаж засах:

• Богино хугацааны түр алдаа байж болох тул backoff-той дахин оролдлого хий.
• Удаан үргэлжилбэл GET /health/ready-аар үйлчилгээний болон DB-ийн төлвийг шалга (энэ endpoint-д auth шаардахгүй).
• Тогтмол давтагдвал хүсэлтийн цаг, дамжуулсан id/refNum-той хамт gov-pay-тэй холбогдоно уу.

Холбоотой хуудас

• Баталгаажуулалт — X-API-Key, rate limit
• Орчин — sandbox / production Base URL-ууд
• Төлбөр — төлбөрийн статусын урсгал, 422 нөхцөл
• Нэхэмжлэл — нэхэмжлэлийн статус, шүүлтүүрүүд
• Webhook — event хүлээн авах