What do SekaliPay API error codes mean?

Errors are identified by HTTP status and code. The code is in error_code for authentication and rate-limit errors, and in message for endpoint errors. Field validation errors use status 422 with an errors list per field and no code.

This page was checked against the API code as of October 16, 2026.

How many error response shapes are there?#

Shape	Appears when	Code is in
Authentication and limits	The API key, IP, signature, or rate limit is the problem	`error_code`
Endpoint	An endpoint's business rules reject the request	`message`
Validation (`422`)	A request field is invalid	No code; see `errors`

{
  "success": false,
  "message": "Access denied. Your IP address is not whitelisted.",
  "your_ip": "203.0.113.10",
  "error_code": "IP_NOT_WHITELISTED"
}

{
  "status": false,
  "message": "AMOUNT_OUT_OF_RANGE",
  "data": {
    "min_amount": 10000,
    "max_amount": 10000000
  }
}

{
  "message": "Amount must be an integer",
  "errors": {
    "amount": [
      "Amount must be an integer"
    ]
  }
}

Always send Accept: application/json

Without this header, validation errors come back as a 302 redirect to the SekaliPay home page instead of a JSON 422. A wrong URL returns an HTML 404 page.

Which error codes exist?#

HTTP	Code	Meaning
401	MISSING_API_KEY	The `X-API-Key` header was not sent.
401	INVALID_API_KEY	The API key is wrong, has been replaced, or the account is not active.
403	IP_WHITELIST_NOT_CONFIGURED	IP Whitelist mode is on but no IP is registered. Add an IP, or turn the whitelist off to use Enhanced HMAC.
403	IP_WHITELIST_INVALID	The account's whitelist configuration is broken. Contact support.
403	IP_NOT_WHITELISTED	The sender IP is not registered. Register the IP shown in `your_ip`.
401	MISSING_SIGNATURE	A POST request in IP Whitelist mode without an `X-Signature` header.
401	INVALID_SIGNATURE	The body signature does not match. Sign exactly the bytes you send.
401	MISSING_HMAC_SIGNATURE	Enhanced HMAC mode is on but `X-Signature` or `X-Timestamp` was not sent.
401	TIMESTAMP_EXPIRED	`X-Timestamp` is more than 300 seconds away from server time. Compare it with `data.server_time`.
401	INVALID_HMAC_SIGNATURE	The Enhanced HMAC signature does not match. Check PATH, the order and encoding of PARAMS, and the timestamp.
429	RATE_LIMIT_EXCEEDED	The per-minute limit was exceeded. Wait `retry_after` seconds.
403	MERCHANT_KYC_INCOMPLETE	Merchant verification is incomplete. `data.onboarding_url` points to the page to complete it.
400	PAYMENT_METHOD_NOT_AVAILABLE	Unknown method code, or the method is currently disabled.
403	PAYMENT_METHOD_NOT_ENABLED	The method exists but is not enabled on your account.
400	AMOUNT_OUT_OF_RANGE	The amount is outside the method's range; `data` holds `min_amount` and `max_amount`.
409	PAYMENT_ALREADY_EXISTS	This `merchant_ref_id` already has a payment; `data` contains it.
409	DUPLICATE_REF_ID	Two requests with the same ref arrived at the same time and this one lost. Check that ref's status.
500	PAYMENT_GATEWAY_ERROR	The payment partner rejected the request or did not answer. Nothing was stored; retry with the same ref or another method.
404	PAYMENT_NOT_FOUND	No payment with that `merchant_ref_id` exists on this account.
400	BANK_NOT_VERIFIED	The payout account has not been verified in the dashboard.
400	BANK_DETAILS_INCOMPLETE	The payout account details are incomplete.
400	INSUFFICIENT_BALANCE	The available balance is less than `amount` plus the fee; `data.shortage` is the difference.
400	PENDING_SETTLEMENT_EXISTS	Another withdrawal is still in progress. Wait for it to finish.
400	WITHDRAWAL_REJECTED	The withdrawal was refused because the account changed while it was being processed. Check your balance and payout account, then try again.
503	PAYOUT_UNAVAILABLE	The transfer service cannot process withdrawals right now (on our side, not your balance). Try again in a few minutes.
500	INTERNAL_SERVER_ERROR	An error on our side; details are not sent. Retry, or contact support with the time and `merchant_ref_id`.
503	SERVICE_UNAVAILABLE	The service is temporarily unavailable. Retry after `Retry-After` seconds.

How do I read validation errors?#

Status 422 means one or more fields are invalid. errors maps each field name to a list of messages. Messages may be in English or Indonesian, so log them for your team rather than branching on them.

422 Unprocessable Content

{
  "message": "Amount must be an integer",
  "errors": {
    "amount": [
      "Amount must be an integer"
    ]
  }
}

Which errors are safe to retry?#

Status	Retry?	Notes
400, 401, 403, 404, 409, 422	No	Fix the request, keys, or configuration first.
429	Yes	Wait for the `Retry-After` header.
503	Yes	A temporary problem on our side. Wait for `Retry-After`.
500 and timeouts	Carefully	`POST /payment`: retry with the same `merchant_ref_id`, which is safe (idempotency). `POST /withdrawal`: never retry automatically; check your balance and history first.

Ready to use your own keys?

Sign in to the merchant dashboard to copy your API key and secret key, set the access mode and webhook URL, and download a Postman collection with your account's keys.