Error Handling
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.
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
Code
Response · HTTP 400
Code
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
429withresponseCode: "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
originalReferenceNoororiginalPartnerReferenceNoshares 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
Response · HTTP 429
Code
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
Illustrative failed response · HTTP 200
Code
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.