Error Reference
Complete error code reference — API errors by service, transaction decline codes, and status codes.
DCMS uses structured error responses to help you diagnose and handle failures programmatically. Every error includes a machine-readable code and a human-readable message.
Error Response Format
All errors follow the standard envelope:
{
"result": null,
"exception": {
"errorCode": "card.not.found",
"errorMessage": "No card found for the given entity and kit"
}
}| Field | Type | Description |
|---|---|---|
errorCode | string | Machine-readable error identifier (dot-notation) |
errorMessage | string | Human-readable description |
Always check the exception field — even on HTTP 200 responses. Some business-level errors return 200 with a populated exception object.
Error Handling Best Practices
- Match on
errorCode— not onerrorMessage(messages may change) - Retry on 5xx — use exponential backoff with jitter
- Do not retry on 4xx — fix the request before resending
- Log the full response — including headers and request ID for support
- Map to user-friendly messages — never show raw error codes to end users
Wallet Load POST
Loads funds into the wallet associated with a kit. This API is used to add money to NCMC (National Common Mobility Card) wallets. The wallet balance will be updated after a successful load. The response includes both the current wallet balance and the staged wallet balance which represents the pending amount.
API Error Codes
Error codes organized by service — Customer Service, Config Service, CMS, CBS Connector, Auth Service, OTP Manager, and Fee Posting.