M2P Fintech API documentation

Complete catalog of error codes across the M2P Prepaid Platform. Use these codes to implement accurate error handling and clear user-facing messages.

Error Response Format

All API errors follow a consistent JSON structure:

{
  "status": "error",
  "error": {
    "code": "TXN_003",
    "message": "Insufficient balance",
    "description": "The wallet balance is insufficient for this transaction",
    "httpStatus": 400
  },
  "timestamp": "2026-03-06T10:30:00Z",
  "requestId": "req_abc123"
}

Field	Type	Description
`code`	`string`	Machine-readable error code — use for programmatic handling
`message`	`string`	Short error summary
`description`	`string`	Detailed human-readable explanation
`httpStatus`	`integer`	HTTP status code
`requestId`	`string`	Unique request identifier — include in support tickets

Error Categories

Authentication (AUTH_xxx)

Registration (REG_xxx)

Validation errors, duplicate detection, and bank registration failures.

Transaction (TXN_xxx)

Insufficient balance, limit exceeded, invalid amounts, and reversal errors.

Card (CARD_xxx)

Invalid card status, PIN errors, and physical card issues.

Tokenization (TOK_xxx)

Token eligibility, token not found, and network service failures.

System (SYS_xxx)

Internal errors, timeouts, and service unavailability.

Network Response Codes

ISO 8583 response codes from Visa, Mastercard, and RuPay networks.

Error Handling Quick Reference

Practice	Implementation
Map error codes to user messages	Translate M2P codes into friendly messages for your end users
Retry on 5xx only	Server errors may be transient — use exponential backoff
Do not retry 4xx	Client errors require request correction, not retry
Log error details	Store `requestId`, `code`, and `timestamp` for debugging
Monitor error patterns	Alert on repeated `AUTH_008` (rate limit) or `SYS_001` (server errors)

Error Codes