# Error Handling

> This SNAP Disbursement guide is currently available in English.

Identify request errors, understand failure details, and choose the appropriate recovery action.

## Read an error response

For a rejected API request, inspect `responseCode` and `responseMessage`. For a failed transfer returned by a successful inquiry, inspect `errorCode`, `errorDetailCode`, and `failureMessage`.

Use the code returned by the endpoint; do not substitute a transaction error code for a request-validation error. For transaction lifecycle information, see [Check Status](/brickfast-disbursement/snap/check-status).

## Authentication and access errors

| Error condition | How to resolve it |
| --- | --- |
| Missing, empty, invalid, or expired access token | Send a valid SNAP token in the Authorization header. Replace it if it has expired. |
| Missing Bearer prefix or Basic authentication | Use Bearer authentication, not Basic authentication. |
| Client ID and token mismatch | Use a token belonging to the Client ID supplied in X-CLIENT-KEY. |
| Invalid signature or signature from another key | Sign with the private key corresponding to your registered public key. Check the signing path and payload. |
| Request changed after signing | Re-sign the final body and timestamp before sending the request. |
| Timestamp outside the accepted window | Synchronize your system clock and generate a fresh timestamp and signature. |
| Account not permitted to use disbursement | Contact Brick to confirm access. Creating another token does not grant additional permissions. |

Invalid-token requests return HTTP `401`. The invalid-token response code is `4010101` for Regular transfers and `4010301` for Check Status. Signature failures, out-of-window timestamps, and disbursement access restrictions also return HTTP `401`; inspect the returned message to distinguish the cause.

Do not automatically create a new token for every HTTP 401. Refreshing a token will not fix an incorrect signature or an account access restriction.

## Request headers and JSON validation

| Error condition | How to resolve it |
| --- | --- |
| Missing required headers | Include Content-Type, X-CLIENT-KEY, X-TIMESTAMP, X-SIGNATURE, and the headers required by the endpoint. |
| Malformed timestamp | Use an ISO 8601 timestamp with a timezone. |
| Empty request body or malformed JSON | Send a valid JSON object with the required fields and Content-Type: application/json. |
| Unsupported HTTP method | Use POST for all four SNAP Disbursement endpoints. |
| Missing or empty mandatory field | Populate the field identified in the response. Check nested amount and sender fields as applicable. |

Correct the request before retrying. When changing the body or timestamp, generate a new signature.

## Active token limit — HTTP 429

Each successful token creation request returns a new token. When **5 non-expired tokens** are active, another token cannot be created until at least one expires.

Reuse an existing valid token. Each token lasts **900 seconds**. Repeated token creation attempts do not free an active token slot.

## Missing mandatory field — HTTP 400

This Regular transfer request omits `partnerReferenceNo`.

**Request · cURL**

```bash
curl --request POST \
  --url '{{base_url}}/v2/payments/disbursements/snap/regular-transfer' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer snap_demo_20261020_83ac67125b8f' \
  --header 'X-CLIENT-KEY: 83ac6712-5b8f-4b0d-9e24-63aa79102d45' \
  --header 'X-TIMESTAMP: 2026-10-20T09:00:00+07:00' \
  --header 'X-SIGNATURE: U05BUC1ET0NTLUVYQU1QTEUtU0lHTkFUVVJFLU5PVC1GT1ItQVVUSA==' \
  --header 'X-REFERENCE-ID: 61fd8e9b-4c37-4d5a-83bd-2b4589c0a621' \
  --data-raw '{
  "transferType": "REGULAR",
  "amount": {
    "value": "29999.00",
    "currency": "IDR"
  },
  "beneficiaryAccountNo": "112233445",
  "beneficiaryBankCode": "MANDIRI",
  "beneficiaryAccountName": "PROD ONLY",
  "beneficiaryEmail": "",
  "remark": "Payment"
}'
```

**Response · HTTP 400**

```json
{
  "responseCode": "4000102",
  "responseMessage": "Invalid Mandatory Field partnerReferenceNo"
}
```

## Invalid field values and formats

| Error condition | How to resolve it |
| --- | --- |
| amount is null or is not an object | Provide an amount object containing value and currency. |
| amount.value is numeric or has an invalid decimal format | Send a string with exactly two decimal places, for example "29999.00". |
| Zero, negative, or out-of-range amount | Use a positive amount within the supported limits for your transfer method. Confirm limits with Brick if needed. |
| Unsupported currency | Use IDR. |
| Unsupported or mismatched transferType | Use REGULAR on the Regular endpoint and BI_FAST on the BI-FAST endpoint. |
| Account number or business reference sent as a number | Send these values as strings; preserve leading zeros. |
| Remark exceeds the supported length | Shorten the remark to the supported length. Confirm the limit with Brick if needed. |
| Missing BI-FAST sender information | Provide all required sender fields described in the BI-FAST API Reference. |

Invalid field formats are rejected before a new transfer is created. The generic Regular request-layer format code is `4000101`; use the specific code and field description returned by the endpoint when available.

## Bank, balance, and duplicate-reference errors

| Error condition | How to resolve it |
| --- | --- |
| Unsupported beneficiary bank | Check the bank code and whether the bank is supported by your selected transfer method. |
| Insufficient client balance | Check your available Brick balance and fund the account before submitting a new transfer. Do not confuse a client-balance rejection with a provider funding issue. |
| Duplicate partnerReferenceNo | Check the original transaction using its reference. Do not submit another transfer for the same payout until its outcome is known. |
| Duplicate partnerReferenceNo with a changed amount | Changing the amount does not make a reused business reference a new transfer. Use a new reference only for a genuinely new transfer. |

A duplicate-reference rejection does not create a second transfer. The original references remain available for inquiry.

## Status inquiry errors

| Error condition | How to resolve it |
| --- | --- |
| Both reference fields supplied | Send exactly one of originalReferenceNo or originalPartnerReferenceNo. |
| Missing, empty, or incorrectly typed reference | Provide the original transaction reference as a non-empty string, not a number or object. |
| Missing or unsupported serviceCode | Use string "01" for Regular or "02" for BI-FAST. Do not use the inquiry endpoint’s own code as the original service. |
| Reference and serviceCode do not match | Use the service code of the original transfer. |
| Transaction not found — HTTP 404 | Verify the reference, environment, service code, and account credentials. Transactions outside your account are not disclosed. |

The generic invalid-format code for an unsupported original service is `4000301`. Empty or missing values may use a different validation response. A not-found response does not by itself prove that a transfer submission failed; resolve the reference before initiating a replacement.

## Status inquiry limit — HTTP 429

For the same authenticated client and the same transaction:

- A maximum of **5 Check Status requests** is allowed within a **30-second window**.
- The **6th and subsequent requests** within that window return HTTP `429` with `responseCode: "4290300"`.
- The limit applies only to the affected transaction. **Other transactions under the same authenticated client remain unaffected** and have their own inquiry limits.
- Looking up the same transaction using `originalReferenceNo` or `originalPartnerReferenceNo` shares the same limit.

Wait for the affected transaction’s rate-limit window to reset before trying again.

The response below applies when the inquiry limit has already been reached.

**Request · cURL**

```bash
curl --request POST \
  --url '{{base_url}}/v2/payments/disbursements/snap/status' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer snap_demo_20261020_83ac67125b8f' \
  --header 'X-CLIENT-KEY: 83ac6712-5b8f-4b0d-9e24-63aa79102d45' \
  --header 'X-TIMESTAMP: 2026-10-20T09:00:00+07:00' \
  --header 'X-SIGNATURE: U05BUC1ET0NTLUVYQU1QTEUtU0lHTkFUVVJFLU5PVC1GT1ItQVVUSA==' \
  --header 'X-REFERENCE-ID: 61fd8e9b-4c37-4d5a-83bd-2b4589c0a621' \
  --data-raw '{
  "originalReferenceNo": "BRICK-20261020-0001",
  "serviceCode": "01"
}'
```

**Response · HTTP 429**

```json
{
  "responseCode": "4290300",
  "responseMessage": "Too Many Requests"
}
```

**Two separate limits** The active-token limit applies to token creation. The inquiry limit applies to Check Status. Do not treat them as the same limit.

## Failed transfer response

A status inquiry can succeed while reporting that the underlying transfer failed. The following example illustrates that distinction.

**Request · cURL**

```bash
curl --request POST \
  --url '{{base_url}}/v2/payments/disbursements/snap/status' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer snap_demo_20261020_83ac67125b8f' \
  --header 'X-CLIENT-KEY: 83ac6712-5b8f-4b0d-9e24-63aa79102d45' \
  --header 'X-TIMESTAMP: 2026-10-20T09:00:00+07:00' \
  --header 'X-SIGNATURE: U05BUC1ET0NTLUVYQU1QTEUtU0lHTkFUVVJFLU5PVC1GT1ItQVVUSA==' \
  --header 'X-REFERENCE-ID: 61fd8e9b-4c37-4d5a-83bd-2b4589c0a621' \
  --data-raw '{
  "originalReferenceNo": "BRICK-REG-20261020-0003",
  "serviceCode": "01"
}'
```

**Illustrative failed response · HTTP 200**

```json
{
  "responseCode": "2000300",
  "responseMessage": "Successful",
  "originalReferenceNo": "BRICK-REG-20261020-0003",
  "originalPartnerReferenceNo": "SNAP-REG-20261020-0003",
  "serviceCode": "01",
  "latestTransactionStatus": "06",
  "transactionStatusDesc": "Failed",
  "errorCode": "5000100",
  "errorDetailCode": "general_error",
  "failureMessage": "General Error",
  "category": "Failed"
}
```

This transfer has failed. Check `errorCode`, `errorDetailCode`, and `failureMessage` for the failure reason. Resolve correctable issues before initiating a new transfer.

## Timeouts and safe retries

A timeout or missing response is not proof of a failed transfer. Keep the original `partnerReferenceNo` and use [Check Status](/brickfast-disbursement/snap/check-status) to resolve the outcome before submitting a replacement. If it remains unresolved, contact Brick.

## Contacting support

Provide the endpoint, request time, `X-REFERENCE-ID`, transaction references, and returned response or failure details. Do not share private keys, access tokens, or authentication secrets.