Skip to main content
All Singapay API responses include a response_code field that indicates whether your API request was received and processed correctly by the server.
Response codes are not transaction statuses. A response_code tells you the result of the request itself — whether the server accepted it, rejected it due to validation, or encountered an error. It does not tell you whether the underlying payment succeeded, is pending, or failed. To track the actual payment outcome, use the transaction_status object in the response body or wait for the webhook callback. See Transaction Status for the full lifecycle.
For example, a disbursement request may return response_code: "SP000" (request accepted successfully) while the payment itself is still "Initiated" — the money has not moved yet. Conversely, a webhook may arrive with response_code: "SP001" to notify you that a previously accepted transaction has now failed at the provider.

​
Response format

{
  "response_code": "SP000",
  "response_message": "Successfully",
  "data": { ... }
}

​
Response code dictionary

Each code below describes a request-level outcome — not the state of the payment or transfer.

​
Success

CodeMessageDescription
SP000SuccessfullyThe request was accepted and processed. For transactional endpoints, this means the request was submitted — not that the payment is complete. Check transaction_status for the payment outcome.

​
Transaction request errors

CodeMessageDescriptionRecommended action
SP001Transaction FailureThe transaction failed during processing.Call the inquiry-status endpoint to confirm the final state.
SP002General FailureAn internal server error occurred.Retry after a short delay; call inquiry-status if the issue persists.
SP003Insufficient BalanceThe account does not have enough balance to complete the transaction.Top up the account and retry.
SP004Duplicate Reference NumberA transaction with this reference_number already exists.Use a unique reference number for each new transaction.
SP005TimeoutThe upstream provider did not respond in time.Call the inquiry-status endpoint — the transaction may still settle.
SP006Exceed Beneficiary LimitThe beneficiary has reached their daily or per-transaction limit.Retry with a lower amount or try again the next business day.
SP007Exceed Account LimitYour account has reached its transaction limit.Contact Singapay support to review your limits.

​
Lookup errors

CodeMessageDescriptionRecommended action
SP008Invalid Reference NumberThe reference number does not match any transaction.Verify the reference number and retry.
SP009Transaction Not FoundNo transaction exists for the given ID.Confirm the transaction_id is correct.
SP010Beneficiary Account Not FoundThe destination bank account could not be found.Verify the account number and bank code.
SP011Beneficiary Vendor Not ActiveThe payment vendor/channel is currently unavailable.Try an alternative channel or retry later.
SP020Merchant Account Not FoundThe specified merchant account does not exist.Verify the account_id in the request.

​
Authentication & authorization errors

CodeMessageDescriptionRecommended action
SP013UnauthorizedInvalid or expired access token.Request a new token via Access Token v1.1.
SP015ForbiddenThe token is valid but lacks permission for this action.Verify account permissions in the merchant dashboard.
SP016Signature InvalidThe X-Signature header could not be verified.Review Security and signature validation.
SP017Unauthorized IPThe request originated from a non-whitelisted IP.Add your server IP in the merchant dashboard, or contact support.

​
Request errors

CodeMessageDescriptionRecommended action
SP012Bad RequestThe request body is malformed or missing required fields.Check the request against the endpoint schema.
SP014Not FoundThe requested resource or endpoint does not exist.Verify the URL path and resource ID.
SP018Validation ErrorOne or more fields failed validation.Check the data.errors object for field-level details.
SP019General ErrorAn unclassified server-side error occurred.Contact Singapay support with the transaction_id and timestamp.

​
HTTP status code mapping

Singapay REST API endpoints also return standard HTTP status codes. Here is how they map to common scenarios:
HTTP StatusMeaningTypical cause
200OKRequest succeeded.
400Bad RequestMalformed body, missing fields, or transaction failure (v2 endpoints).
401UnauthorizedInvalid JWT, expired token, partner mismatch, or revoked credentials.
403ForbiddenIP not whitelisted, account access denied, or merchant frozen.
404Not FoundResource (account, transaction, VA) does not exist.
422Unprocessable EntityValidation error — usually a missing X-PARTNER-ID header or invalid field values.
500Internal Server ErrorUnexpected server error. Retry or contact support.
v2 endpoints (Card, E-Wallet Native v2, Disbursement v2, QRIS Issuer) return both an HTTP status code and an SP response code in the body. Always check the response_code field for the definitive result.

​
Handling response codes

1

Check the response code

Parse response_code from the JSON body. SP000 means the request was accepted — proceed to check the transaction_status for the actual payment outcome.
2

Handle known errors

Match against the tables above. Errors like SP003 (insufficient balance) or SP004 (duplicate reference) have clear resolutions.
3

Handle known request errors

Match against the tables above. Errors like SP003 (insufficient balance) or SP004 (duplicate reference) have clear resolutions.
4

Don't confuse request success with payment success

SP000 confirms the server accepted your request. The payment may still be Initiated, Paying, or Pending. Always read the transaction_status object or wait for the webhook callback to determine the final payment outcome. See Transaction Status for the full lifecycle.
5

Use inquiry-status for uncertain outcomes

For SP001, SP002, and SP005, the transaction may still be in progress. Call the relevant inquiry-status endpoint before retrying.
6

Contact support for persistent errors

If SP007, SP017, or SP019 persists, contact Singapay support with the full request and response payloads.
Never retry a transaction blindly after a failure. Always call the inquiry-status endpoint first to confirm the final state. Retrying without checking can result in duplicate transfers.