> ## Documentation Index
> Fetch the complete documentation index at: https://docs.singapay.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Codes

> Complete dictionary of Singapay API response codes (SP-codes) returned across all endpoints and webhooks.

All Singapay API responses include a `response_code` field that indicates whether your **API request** was received and processed correctly by the server.

<Warning>
  **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](/api-reference/webhooks/introduction). See [Transaction Status](/api-reference/references/transaction-status) for the full lifecycle.
</Warning>

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

<CodeGroup>
  ```json REST API (v2 endpoints) theme={null}
  {
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": { ... }
  }
  ```

  ```json Webhook callback theme={null}
  {
    "response_code": "SP000",
    "response_message": "Successfully",
    "event": "disbursement",
    "data": { ... }
  }
  ```
</CodeGroup>

***

## Response code dictionary

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

### Success

| Code    | Message      | Description                                                                                                                                                                                           |
| ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SP000` | Successfully | The 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

| Code    | Message                    | Description                                                           | Recommended action                                                    |
| ------- | -------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `SP001` | Transaction Failure        | The transaction failed during processing.                             | Call the inquiry-status endpoint to confirm the final state.          |
| `SP002` | General Failure            | An internal server error occurred.                                    | Retry after a short delay; call inquiry-status if the issue persists. |
| `SP003` | Insufficient Balance       | The account does not have enough balance to complete the transaction. | Top up the account and retry.                                         |
| `SP004` | Duplicate Reference Number | A transaction with this `reference_number` already exists.            | Use a unique reference number for each new transaction.               |
| `SP005` | Timeout                    | The upstream provider did not respond in time.                        | Call the inquiry-status endpoint — the transaction may still settle.  |
| `SP006` | Exceed Beneficiary Limit   | The beneficiary has reached their daily or per-transaction limit.     | Retry with a lower amount or try again the next business day.         |
| `SP007` | Exceed Account Limit       | Your account has reached its transaction limit.                       | Contact Singapay support to review your limits.                       |

### Lookup errors

| Code    | Message                       | Description                                          | Recommended action                         |
| ------- | ----------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| `SP008` | Invalid Reference Number      | The reference number does not match any transaction. | Verify the reference number and retry.     |
| `SP009` | Transaction Not Found         | No transaction exists for the given ID.              | Confirm the `transaction_id` is correct.   |
| `SP010` | Beneficiary Account Not Found | The destination bank account could not be found.     | Verify the account number and bank code.   |
| `SP011` | Beneficiary Vendor Not Active | The payment vendor/channel is currently unavailable. | Try an alternative channel or retry later. |
| `SP020` | Merchant Account Not Found    | The specified merchant account does not exist.       | Verify the `account_id` in the request.    |

### Authentication & authorization errors

| Code    | Message           | Description                                              | Recommended action                                                                                             |
| ------- | ----------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `SP013` | Unauthorized      | Invalid or expired access token.                         | Request a new token via [Access Token v1.1](https://docs.singapay.id/api-reference/security/access-token-v11). |
| `SP015` | Forbidden         | The token is valid but lacks permission for this action. | Verify account permissions in the merchant dashboard.                                                          |
| `SP016` | Signature Invalid | The `X-Signature` header could not be verified.          | Review [Security and signature validation](/api-reference/webhooks/security-and-signature).                    |
| `SP017` | Unauthorized IP   | The request originated from a non-whitelisted IP.        | Add your server IP in the merchant dashboard, or contact support.                                              |

### Request errors

| Code    | Message          | Description                                               | Recommended action                                                |
| ------- | ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------- |
| `SP012` | Bad Request      | The request body is malformed or missing required fields. | Check the request against the endpoint schema.                    |
| `SP014` | Not Found        | The requested resource or endpoint does not exist.        | Verify the URL path and resource ID.                              |
| `SP018` | Validation Error | One or more fields failed validation.                     | Check the `data.errors` object for field-level details.           |
| `SP019` | General Error    | An 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 Status | Meaning               | Typical cause                                                                       |
| ----------- | --------------------- | ----------------------------------------------------------------------------------- |
| `200`       | OK                    | Request succeeded.                                                                  |
| `400`       | Bad Request           | Malformed body, missing fields, or transaction failure (v2 endpoints).              |
| `401`       | Unauthorized          | Invalid JWT, expired token, partner mismatch, or revoked credentials.               |
| `403`       | Forbidden             | IP not whitelisted, account access denied, or merchant frozen.                      |
| `404`       | Not Found             | Resource (account, transaction, VA) does not exist.                                 |
| `422`       | Unprocessable Entity  | Validation error — usually a missing `X-PARTNER-ID` header or invalid field values. |
| `500`       | Internal Server Error | Unexpected server error. Retry or contact support.                                  |

<Info>
  **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.
</Info>

***

## Handling response codes

<Steps>
  <Step title="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.
  </Step>

  <Step title="Handle known errors">
    Match against the tables above. Errors like `SP003` (insufficient balance) or `SP004` (duplicate reference) have clear resolutions.
  </Step>

  <Step title="Handle known request errors">
    Match against the tables above. Errors like `SP003` (insufficient balance) or `SP004` (duplicate reference) have clear resolutions.
  </Step>

  <Step title="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](/api-reference/webhooks/introduction) to determine the final payment outcome. See [Transaction Status](/api-reference/references/transaction-status) for the full lifecycle.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Contact support for persistent errors">
    If `SP007`, `SP017`, or `SP019` persists, contact Singapay support with the full request and response payloads.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>