SNAP Disbursement 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.

SNAP response examples

Use these response codes and messages for the corresponding SNAP Disbursement conditions.

API and condition	HTTP status	responseCode	responseMessage
Authentication: missing `X-CLIENT-KEY`	401	`4017300`	`Unauthorized X-CLIENT-KEY`
Authentication, Regular, BI-FAST, or Check Status: malformed `X-TIMESTAMP` or timestamp outside the accepted window	401	`4011100`	`Unauthorized. X-TIMESTAMP must be RFC3339 and within ten minutes of server time`
Authentication: 5 active tokens already exist	429	`4297300`	`Too many active SNAP tokens. Please wait for an existing token to expire.`
Regular, BI-FAST, or Check Status: invalid access token	401	`4010103`	`Token Not Found (B2B)`
Regular or BI-FAST: invalid `transferType` format	400	`4000101`	`Invalid Field Format transferType`
Check Status: transaction not found or owned by another client	404	`4040300`	`referenceId or brickTransactionId not found`
Authentication or Regular: invalid signature	401	`4010100`	`Unauthorized. X-SIGNATURE does not match the registered public key and request payload`
Regular or BI-FAST: client has no disbursement access	401	`4010100`	`Unauthorized. Your client account is inactive for this specific service`

The same 4010100 response code is used for the two authorization failures above; use responseMessage to distinguish the cause.

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.
Malformed timestamp or timestamp outside the accepted window	Use RFC3339 / ISO 8601 with a timezone. Synchronize your system clock and generate a fresh timestamp and signature within plus or minus 10 minutes of server time.
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 with responseCode 4010103. Signature failures 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 RFC3339 / ISO 8601 timestamp with a timezone, within plus or minus 10 minutes of server time.
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.

Invalid X-TIMESTAMP — HTTP 401

This response applies when X-TIMESTAMP is not RFC3339 / ISO 8601 with a timezone, or when its time is more than 10 minutes before or after server time.

Code
{
  "responseCode": "4011100",
  "responseMessage": "Unauthorized. X-TIMESTAMP must be RFC3339 and within ten minutes of server time"
}

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.

Code
{
  "responseCode": "4297300",
  "responseMessage": "Too many active SNAP tokens. Please wait for an existing token to expire."
}

Missing mandatory field — HTTP 400

This Regular transfer request omits partnerReferenceNo.

Request · cURL

Code
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

Code
{
  "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.

Code
{
  "responseCode": "4040300",
  "responseMessage": "referenceId or brickTransactionId not found"
}

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

Code
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

Code
{
  "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

Code
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

Code
{
  "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 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.

Last modified on November 2, 2026