স্থায়ী reason code
স্থায়ী error code client logic, report এবং inquiry-এর automatic routing-এ ব্যবহৃত হয়।
Documentation / API error
API error handling
iGaming integration-এর জন্য response, error code, temporary failure, unknown result, diagnostics এবং safe recovery-এর একক model।
HTTP
request result
Code
স্পষ্ট কারণ
Retry
নিরাপদ action
Search
request diagnostics
Error handling cycle
API response থেকে recovery পর্যন্ত
01
Result type নির্ধারণ করুন
HTTP status, reason code, error category এবং operation state যাচাই করুন।
02
বিশ্লেষণের data সংরক্ষণ করুন
Request ও operation ID, method endpoint, time, provider reference এবং safe parameter record করুন।
03
নিরাপদ action নির্বাচন করুন
Data ঠিক করুন, operation থামান, বিরতি দিয়ে request retry করুন অথবা current state যাচাই করুন।
04
Recover ও monitor করুন
Duplicate বাদ দিন, reconciliation করুন, দায়িত্বপ্রাপ্তদের জানান এবং failure-এর কারণ বন্ধ করুন।
Overview
Error-এ কারণ ও পরবর্তী action স্পষ্ট হওয়া উচিত
শুধু HTTP 400 বা 500 যথেষ্ট নয়। নির্ভরযোগ্য API স্থায়ী reason code দেয়, response-কে request ID-এর সঙ্গে যুক্ত করে এবং data ঠিক করা, operation বন্ধ করা, request retry করা নাকি state আলাদাভাবে যাচাই করা দরকার তা বোঝায়।
পূর্বানুমেয় action
Error category request retry করা যাবে কি না এবং কোন data পরিবর্তন করতে হবে তা দেখায়।
Diagnostics-এর linkage
Request, operation এবং provider ID client log-কে internal system ও support-এর সঙ্গে যুক্ত করে।
Error structure
প্রস্তাবিত error response structure
Response সংক্ষিপ্ত, স্থায়ী এবং internal implementation বা sensitive data প্রকাশ না করে automated processing-এর উপযোগী হওয়া উচিত।
Error code
Reason-এর স্থায়ী identifier, explanation message সম্পাদনা হলেও যা পরিবর্তিত হয় না।
Description
Internal code, database query, secret বা অপ্রয়োজনীয় detail ছাড়া সংক্ষিপ্ত নিরাপদ ব্যাখ্যা।
Request ID
Log-এ operation খোঁজা এবং support-এ যোগাযোগের জন্য unique identifier।
অতিরিক্ত data
Allowed status, limit, current state অথবা নিরাপদ refusal reason।
Retry করা যাবে
Temporary error-এর স্পষ্ট indicator, যা operation-এর duplicate protection বাতিল করে না।
Retry-এর আগে বিরতি
Rate limit ও temporary unavailability-এর জন্য recommended delay in seconds অথবা HTTP header।
Field error
Reason code, value path এবং নিরাপদ explanation-সহ সমস্যাযুক্ত field-এর তালিকা।
Documentation link
Reason ও correction method বর্ণনা করা section-এর স্থায়ী link বা identifier।
Error category
প্রধান error category
HTTP status result-এর সাধারণ class দেখায়, আর internal code নির্দিষ্ট কারণ ও অনুমোদিত action স্পষ্ট করে।
Input data error
ভুল format, অনুপস্থিত required field, unsupported value, amount precision error অথবা ভাঙা request structure।
Authentication error
অনুপস্থিত, expired বা invalid token, API key, signature, request time অথবা one-time identifier।
Permission অপর্যাপ্ত
Client শনাক্ত হয়েছে, কিন্তু প্রয়োজনীয় role, brand, market বা action permission নেই।
Object পাওয়া যায়নি
Player, payment, round, KYC check, provider বা অন্য object নেই অথবা client-এর জন্য unavailable।
State conflict
Object-এর version বা state বদলেছে, অথবা operation ID অন্য parameter-সহ আগে ব্যবহার হয়েছে।
Business rule violation
Insufficient balance, limit exceeded, blocked player, prohibited market অথবা invalid status transition।
অতিরিক্ত request
Client, method, role অথবা critical operation-এর অনুমোদিত request limit অতিক্রম করেছে।
Provider unavailable
External service unavailable, দেরিতে response দিচ্ছে অথবা সাময়িকভাবে operation নিচ্ছে না।
Internal error
Internal detail প্রকাশ না করে diagnostics-এর identifier-সহ platform-এর unexpected error।
Retry ও recovery
Request retry ও unknown result
Error type নির্ধারণ এবং original operation ইতিমধ্যে সম্পন্ন হতে পারে কি না যাচাই করার পরই retry নিরাপদ।
01
Retry অনুমোদিত কি না যাচাই করুন
Data, permission এবং business rule error সাধারণত request সংশোধন চায়, পুনরায় পাঠানো নয়।
02
একই operation key রাখুন
Financial, gaming বা অন্য critical operation retry করলে নতুন result তৈরি হওয়া উচিত নয়।
03
চেষ্টার মধ্যে বিরতি বাড়ান
Interval ধীরে ধীরে বাড়ে, server-এর নির্দেশিত সময় মানে এবং মোট attempt সীমিত রাখে।
04
থামুন এবং review-তে পাঠান
Attempt শেষ হলে operation অসম্পূর্ণ হিসেবে record করে manual review বা reconciliation-এ পাঠানো হয়।
Response না পাওয়া মানেই operation ব্যর্থ নয়
Request পাঠানোর পর connection বিচ্ছিন্ন হলে result unknown থাকতে পারে। Retry-এর আগে operation ID দিয়ে state যাচাই করুন অথবা trusted notification-এর অপেক্ষা করুন।
Diagnostics ও control
Log, identifier, metric ও notification
অপ্রয়োজনীয় sensitive data না রেখে diagnostics-কে platform, adapter এবং external provider-এর মধ্যে request path পুনর্গঠন করতে হবে।
বিশ্লেষণের context
Request, correlation, operation এবং external provider ID।
Method endpoint, HTTP method, environment, client, time এবং response duration।
HTTP status, error code, attempt count এবং final state।
Masked sensitive field, safe header এবং signature verification result।
Monitoring ও notification
Method, provider, client এবং reason category অনুযায়ী error rate।
Slow response, HTTP 5xx, invalid signature এবং rate limit বৃদ্ধির হার।
Retry count, unknown-result operation এবং recovery task।
Threshold, owner এবং escalation rule-সহ notification।
Testing
Test environment-এ কী যাচাই করবেন
Test environment-কে প্রতিটি গুরুত্বপূর্ণ error category পুনরুত্পাদন করতে এবং client, retry ও control-এর সঠিক behavior নিশ্চিত করতে হবে।
Input data error
Missing field, invalid type, unsupported value, amount precision এবং একই সঙ্গে একাধিক error।
Access ও permission
Invalid key, expired token, incorrect signature, wrong role, blocked IP এবং repeated one-time identifier।
Response নেই ও result unknown
Request পাঠানোর আগে, operation গ্রহণের পরে এবং final response পাওয়ার সময় connection break।
Rate limit
HTTP 429, recommended delay, parallel request এবং limit শেষ হওয়ার পর recovery।
Provider error
Unavailability, maintenance, invalid response, delayed notification এবং conflicting status।
Retry ও protective stop
Attempt limit, increasing delay, request সাময়িকভাবে বন্ধ, controlled recovery এবং manual escalation।
Launch-পূর্ব checklist
Error structure, client behavior, duplicate protection এবং diagnostics যাচাইয়ের পর production integration চালু হয়।
সব error স্থায়ী reason code ও request ID ফেরত দেয়।
Error detail secret বা internal implementation প্রকাশ করে না।
Temporary ও permanent error category documentation-এ বর্ণিত।
Critical operation retry একই duplicate-protection key ব্যবহার করে।
Unknown result state check বা trusted notification-এর মাধ্যমে handle করা হয়।
Log, metric, notification, recovery queue এবং escalation rule configured আছে।
API error-কে একক format-এ আনতে চান?
বর্তমান HTTP response, error code, retry rule এবং সমস্যাযুক্ত scenario দিন। APIACE একটি unified error model, safe recovery এবং control নির্ধারণে সাহায্য করবে।