Common Error Codes

Error Response Format

API errors follow a consistent response structure.

{
  "errorCode": "INVALID_REQUEST",
  "errorMessage": "Invalid request parameters",
  "requestId": "abc-123-xyz"
}

"Success" Code

⚠️ There is no single "Success" code common to the entire B2B service — this value differs by API group (e.g. 100 or 200 depending on the group). Check the exact value that applies in the corresponding error code table.

Common Error Code Table

The system-level error codes below are shared across all API groups (they are not product-specific business codes):

Error Code	Meaning	Suggested Action
11	Failed	Check request parameters again
101	Baokim system error	Retry after a few seconds; contact Baokim if persists
103	Signature verification error	Check private key and signing algorithm
104	OAuth / JWT authentication error	Get new token, check client_id / client_secret
105	Signature verification error	Check SHA256withRSA signature creation
422	Parameter validation error	Check required fields and data format
710	Sub Merchant not found	Check sub_merchant_code
711	Master Merchant not found	Check master_merchant_code
712	Sub Merchant inactive	Contact Baokim to check account status
713	Master Merchant inactive	Contact Baokim to check account status

Additionally, each API group has its own business error codes (including its own "Success" code) — see the Error Codes [Group Name] page for each API's details.

HTTP Status Code Table

Baokim uses HTTP status codes combined with code in response body:

HTTP Status	Meaning	Description
200	OK	Request processed. Check code in body for success or business error
401	Unauthorized	JWT Token missing or invalid
403	Forbidden	Token valid but no permission for this endpoint
404	Not Found	Endpoint does not exist
422	Unprocessable Entity	Request data invalid (validation failed)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Internal error on Baokim side
504	Gateway Timeout	Timeout — call query API to confirm status before retrying

Note: Most business errors (invalid parameters, transaction not found...) return HTTP 200 with a code different from that API group's "Success" code (100 or 200 depending on the group) in the body — not HTTP 4xx/5xx.

Troubleshooting

Invalid Signature (Error 103 / 105)

• Check signing algorithm: SHA256withRSA (or SHA1withRSA for VA direct).
• Ensure signing the complete raw JSON string of request body, not parsed object.
• Ensure base64 encoding the signature string before placing in Signature header.
• Check private key correct format (PEM) and matches public key provided to Baokim.

Token Expired (Error 104)

• JWT Token has short validity. Implement automatic token refresh when encountering error 104 or when expired_at is near.
• Do not hardcode token — always get new token from OAuth API before calling.

Created Order Successfully but Did Not Receive Webhook

• Check webhook URL configured with Baokim is correct and accessible from the internet.
• Check server returns HTTP 200 correctly (no redirect, no SSL error).
• Check server logs to see if requests from Baokim's IP were received.
• Call transaction query API to confirm actual order status.

Timeout When Creating Transaction

• Do not retry immediately — call query API first to check if transaction already exists.
• If transaction does not exist, retry with same request_id to ensure idempotency.
• Increase client timeout to 30–60 seconds for transaction creation APIs.

Error 422 — Validation Failed

• Check all required fields (✅) were supplied.
• Check request_time format: YYYY-MM-DD H:i:s.
• Check request_id not used before (must be unique per new request).
• See message in response to identify which field failed.