Алдаа боловсруулалт

GovPay channel-api нь алдааг HTTP статус код болон JSON биеэр дамжуулна. Энэ хуудас алдааны загвар, нийтлэг шалтгаан болон танай систем алдаанд хэрхэн зохицох талаар тайлбарлана. Бүх статус кодын нэгдсэн жагсаалтыг Алдааны кодууд хуудаснаас үзнэ үү.

Validation алдаа (400)

Бүх endpoint NestJS ValidationPipe-ийг whitelist + forbidNonWhitelisted горимоор ашигладаг. Энэ нь:

• Хүсэлтийн биед үл мэдэгдэх / зөвшөөрөгдөөгүй талбар байвал → 400.
• Талбарын төрөл буруу (жишээ нь amount-д тоо биш утга) байвал → 400.

Жишээ нь POST /payments дээр илүүдэл талбар явуулбал хүсэлт бүхэлдээ татгалзана:

{ "invoiceId": "5f8d0a3e-1b2c-4d6e-8a9f-0c1d2e3f4a5b", "foo": "bar" }

{
  "statusCode": 400,
  "message": ["property foo should not exist"],
  "error": "Bad Request"
}

GET /invoices дээр шүүлтүүрийг яг нэгийг (ttd, vehicle эсвэл taxRef) дамжуулна. Хоосон эсвэл олон шүүлтүүр өгвөл мөн 400 буцна.

Буруу UUID (400)

{id} бүхий замууд (GET /invoices/{id}, GET /payments/{id}, DELETE /payments/{id} гэх мэт) ParseUUIDPipe-ээр шалгагдана. Зам дахь утга хүчинтэй UUID биш бол endpoint-ийн дотоод логик ажиллахаас өмнө шууд 400 буцна:

GET /api/v1/payments/not-a-uuid   →  400 Bad Request

Төлбөр амжилтгүй (422)

POST /payments хүсэлт зөв боловч төлбөр боловсруулагдаж чадаагүй (жишээ нь нэхэмжлэл хаагдсан, төрийн систем татгалзсан) бол 201 биш, 422 Unprocessable Entity буцна. Бие нь:

{
  "success": false,
  "refNum": "INV-2026-0001",
  "message": "Төлбөр боловсруулах боломжгүй"
}

success: false-ийг шалгаж, refNum болон message-ийг лог-доо хадгал. 422 нь хүсэлтийн формат биш, бизнес логикийн татгалзал гэдгийг анхаар — ижил биеэр дахин оролдох нь ихэвчлэн дахин амжилтгүй болно.

Төрийн системийн алдаа (5xx)

Дээд талын (upstream) төрийн систем — алдаа өгвөл GovPay 5xx буцаана. Дотоод шалтгаан клиентэд задрахгүй: танд ерөнхий мессеж ирэх ба бодит шалтгаан GovPay-ийн дотоод лог-д тэмдэглэгдэнэ. Эдгээр нь түр зуурын байж болох тул дахин оролдох нь зүйтэй (доорх Дахин оролдлого хэсгийг үз).

Алдаанд зохицох

Статус кодоор салгах

4xx (429-ээс бусад) нь клиентийн алдаа — хүсэлтийг засахгүйгээр дахин оролдох нь утгагүй. 429 болон 5xx нь түр зуурын байж болох тул дахин оролдоход тохиромжтой.

Rate limit (429)

API key тус бүрд лимит: 5/сек, 60/мин, 1000/цаг. Хэтэрвэл 429 буцна. Энэ тохиолдолд хүсэлтийн давтамжаа бууруулж, түр хүлээгээд (exponential backoff) дахин оролдоно. Дэлгэрэнгүйг Орчин хуудаснаас үзнэ үү.

Дахин оролдлого (retry)

Дахин оролдох ерөнхий зарчим:

• Зөвхөн 429 ба 5xx-д автоматаар дахин оролд. 4xx-д бүү дахин оролд.
• Exponential backoff ашигла (жишээ нь 1с → 2с → 4с), дээд хязгаартай (3-5 удаа).
• POST /payments-д X-Idempotency-Key-г хүсэлт болгонд өөрчлөхгүй — анхны UUID-аа дахин оролдлогын турш барь.
• Хариу ирээгүй (timeout) тохиолдолд төлбөр амжилттай болсон эсэхийг GET /payments/{id} эсвэл idempotent дахин оролдлогоор баталгаажуул — нэхэмжлэлийг хоёр дахин бүү төл.

curl -X POST \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-Idempotency-Key: 7c1a9b2e-3d4f-4a5b-8c6d-9e0f1a2b3c4d" \
  -H "Content-Type: application/json" \
  -d '{"invoiceId":"5f8d0a3e-1b2c-4d6e-8a9f-0c1d2e3f4a5b"}' \
  "https://sandbox-tts.qpay.mn/api/v1/payments"

Timeout

Дээд талын төрийн системийн хариу удаашрах магадлалтай тул HTTP клиентдээ боломжийн timeout тавь. Timeout-д орвол хүсэлт амжилтгүй гэж шууд бүү тэмдэглэ — POST /payments дээр idempotency key ашигласан бол аюулгүйгээр дахин оролдож, эсвэл GET /payments/{id}-аар бодит статусыг шалга.

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

• Алдааны кодууд — бүх статус кодын нэгдсэн жагсаалт.
• Орчин — base URL болон rate limit.
• Төлбөр — 422, idempotency, статусын урсгал.
• Webhook — хүргэлтийн timeout болон retry.