> ## Documentation Index > Fetch the complete documentation index at: https://docs.bafanglaicai88.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Describe only the public 123hub merchant API documented on this site. The primary endpoint is POST /public/api/multihub/v1. > Preserve API method names, field names, header names, and error codes exactly as documented. Do not invent endpoints or parameters. > Treat every amount as an integer in minor units unless a page explicitly states otherwise. > Never expose, request, or fabricate a merchant secret key. The SDK pages contain reference implementations, not official SDK packages. # Error Codes > Complete reference of 123hub API error codes and recovery actions # Error Codes API errors use a standard response envelope: ```json theme={null} { "success": false, "error": { "code": 6010, "message": "Payment does not exist", "details": null, "context": null }, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "processing_time": 5 } ``` Most errors return HTTP 400. Unknown or rollout-disabled methods return HTTP 404 with code `1002`. Credential-policy or scope denials return HTTP `403` with code `3008`. Tenant-safe resource absence returns HTTP `404`; it never reveals whether another merchant owns the identifier. State and idempotency conflicts return HTTP `409`. Rate limits return HTTP `429` with the standard error envelope and retry headers. Support dependency failures return HTTP `503` with code `2002`. Gateway readiness can return a non-envelope HTTP `503` while dependencies are not ready. Strict DTO validation rejects unknown fields and can return code `9000`. ## Categories | Range | Category | | ------------- | -------------------------------------------- | | `1xxx` | Common API and system errors | | `2xxx` | Payment hub routing/processing errors | | `3xxx` | Authentication and application access errors | | `4xxx` | Provider account errors | | `5xxx` | Customer account errors | | `6xxx` | Payment errors | | `7xxx` | Provider processing errors | | `8xxx` | Data and status errors | | `9xxx` | Validation errors | | `10001–10005` | Public ticket errors | | `11001–11005` | Public refund errors | | `12001` | Public chargeback errors | | `13001–13004` | Public attachment errors | ## Complete Reference | Code | Message | HTTP | Retry | Recovery | | ------- | ---------------------------------------------------------------- | :-------: | :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------- | | `1000` | Common error | 400 | Yes | Retry with backoff; contact support with `request_id` if it persists. | | `1001` | Endpoint not found | 400 | No | Verify the URL. Use `POST /public/api/multihub/v1`. | | `1002` | The method does not exist / is not available | 404 | No | Use a supported `method` value. | | `1003` | Incorrect use of API | 400 | No | Fix the request structure and authentication flow. | | `1004` | The payment system does not exist for this application | 400 | No | Confirm the route/application setup with support. | | `1005` | Invalid request format | 400 | No | Read `error.details.description` and send the missing/valid field. | | `1006` | Invalid Content-Type header | 400 | No | Send `Content-Type: application/json`. | | `1007` | HTTP Method Not Allowed | 400 | No | Use `POST`. | | `1008` | This method not allowed for payment system | 400 | No | Verify the `service_id` supports this `method`. | | `1009` | Invalid provider | 400 | No | Confirm provider configuration with support. | | `1010` | Currency does not exist / is not available | 400 | No | Use a currency enabled for your application and route. | | `1011` | The balance is not set for this application | 400 | No | Ask support to configure the merchant balance. | | `1012` | There are not enough funds on the application | 400 | No | Top up or reduce the withdrawal amount. | | `1013` | Idempotency key was already used with a different request | 409 | No | Recover the original operation or use a new key only for a genuinely new logical operation. | | `2000` | Payment hub error | 400 | Yes | Retry with backoff; contact support if repeated. | | `2001` | Unexpected error | 400 | Yes | Retry with backoff; contact support with `request_id`. | | `2002` | The payment provider/support dependency is not available | 400 / 503 | Yes | Retry later; for support mutations keep the same idempotency key and exact payload. | | `3000` | Authentication error | 400 | No | Recompute `X-Data-Hash` from the exact raw body and secret. | | `3001` | Missing / incorrect X-Data-Application-Id header | 400 | No | Send a positive integer application ID. | | `3002` | Missing / incorrect X-Data-Hash header | 400 | No | Send a 128-character SHA-512 hex hash. | | `3003` | The app does not exist | 400 | No | Check the application ID. | | `3004` | The app is disabled | 400 | No | Contact support or account management. | | `3005` | The app is blocked | 400 | No | Contact support or account management. | | `3006` | IP address not included in the IP whitelist | 400 | No | Send requests from an allowlisted IP. | | `3007` | Application Settings Error | 400 | No | Contact support to repair application settings. | | `3008` | Credential policy denied | 403 | No | Use a credential allowed for this payment currency and `service_id`, or update the credential access policy in Developer Center. | | `3009` | Credential daily request limit exceeded | 429 | Yes, after UTC day rollover | Stop requests until the next UTC day or ask an administrator to raise the credential limit. | | `4000` | Payment provider account error | 400 | No | Contact support to check provider account state. | | `4001` | The authorization data to the payment provider incorrectly | 400 | No | Contact support to repair provider credentials. | | `4002` | Security issues when interacting with the provider | 400 | No | Contact support; do not retry aggressively. | | `5000` | Customer account error | 400 | No | Verify customer account fields. | | `5001` | Account with the payment provider not found | 400 | No | Verify customer/provider account details. | | `5002` | The account in the payment service provider is blocked | 400 | No | Ask the customer to use another account or contact support. | | `6000` | Payment error | 400 | Depends | Inspect `message` and `details`. | | `6001` | Incorrect transaction amount | 400 | No | Send a positive amount in minor units. | | `6002` | Incorrect currency code | 400 | No | Match `amount.currency` to the `service_id` route currency. | | `6003` | Payment verification required | 400 | No | Complete the provider-required verification step. | | `6004` | Insufficient funds | 400 | No | Check `balance.get` and top up before retrying withdrawals. | | `6005` | The monthly limit of input/output is exceeded | 400 | No | Wait for the next merchant-timezone month or request a payout-limit change. | | `6006` | The daily limit of input/output is exceeded | 400 | No | Wait for the next merchant-timezone day or request a payout-limit change. | | `6009` | Payment already exists | 400 | No | Use `payment.status` with the existing `c_id`. | | `6010` | Payment does not exist | 400 | No | Verify `c_id` or `h_id`. `p_id` is not a lookup key. | | `6011` | Payment expired | 400 | No | Create a new payment. | | `6012` | Payment canceled by user | 400 | No | Create a new payment if the customer wants to retry. | | `6013` | The ban on the payment | 400 | No | Contact support or use another route/customer account. | | `6034` | Payment canceled by payment provider | 400 | No | Ask the customer to retry or use another method. | | `6035` | Exceeded Payments | 400 | No | Contact account management to review payout limits, including since-last-settlement rules. | | `6043` | Payment canceled | 400 | No | Create a new payment if needed. | | `6044` | Payment declined | 400 | No | Ask the customer to retry or use another method. | | `6045` | The user's waiting time during the payment has been exceeded | 400 | No | Create a new payment. | | `7000` | Payment provider error | 400 | Yes | Retry later; contact support with provider details if repeated. | | `7001` | Error of interaction between payment provider and payment system | 400 | Yes | Retry with backoff; contact support if repeated. | | `7002` | Payment provider not available | 400 | Yes | Retry later or use another route. | | `7003` | The problem of interaction with the payment provider | 400 | Yes | Retry later; contact support if repeated. | | `8000` | Data error | 400 | No | Verify request data and provider/account configuration. | | `8001` | An error occurred while processing the data | 400 | Depends | Retry once; contact support if repeated. | | `8600` | Invalid bank credentials | 400 | No | Verify account number/IBAN/CBU/CVU/IFSC. | | `8601` | Invalid bank code | 400 | No | Verify the route-specific bank code. | | `8801` | Current payment or operation status does not allow this action | 400 | No | Query status before retrying the action. | | `9000` | Validation error | 400 | No | Fix invalid fields shown in `message` or `details`. | | `10001` | Ticket not found | 404 | No | Verify the public identifier and credential. Cross-tenant tickets return the same response. | | `10002` | Ticket already exists | 409 | No | Use the existing merchant-owned ticket identifier returned by the conflict. | | `10003` | Ticket state does not allow this action | 409 | No | Refresh the ticket and apply only a valid state transition. | | `10004` | Ticket edit window has expired | 409 | No | Add a new comment instead of editing old merchant-authored content. | | `10005` | Ticket attachment is required | 400 | No | Finalize a valid attachment and retry `ticket.create` with its `ready` ID. | | `11001` | Refund request not found | 404 | No | Verify one public `c_id`/`h_id` and the credential. Cross-tenant refunds return the same response. | | `11002` | Payment is not eligible for a refund | 409 | No | Refresh payment/refund status; do not retry unchanged. | | `11003` | Invalid refund amount | 400 | No | Send a positive digit-string in minor units or omit the amount for the current full remainder. | | `11004` | Refund amount exceeds the remaining amount | 409 | No | Query current refund history and submit an amount within the locked remainder. | | `11005` | An active refund request already exists | 409 | No | Query the existing `pending`/`approved` request before starting another. | | `12001` | Chargeback not found | 404 | No | Verify the UUID and credential. Cross-tenant chargebacks return the same response. | | `13001` | Attachment not found | 404 | No | Refresh the visible parent attachment list. | | `13002` | Attachment upload session has expired | 409 | No | Prepare a new session and upload the file again. | | `13003` | Attachment is not ready | 409 | Yes, when scanning | Wait for validation or prepare a new file if the ID was already consumed/wrong-purpose. | | `13004` | Attachment was rejected | 409 | No | Replace or correct the file; do not retry the rejected bytes. | ## Common Fixes | Symptom | Likely Code | Fix | | -------------------------------- | ------------------------ | ----------------------------------------------------------------- | | Signature mismatch | `3000` | Hash the exact raw JSON string sent in the HTTP body. | | Missing payer on deposit | `1005` | Add `params.payment.payer`. | | Duplicate merchant reference | `6009` | Query the existing payment by `c_id`. | | Currency route mismatch | `6002` | Use the currency assigned to the `service_id`. | | Unknown method | `1002` | Use one of the documented API methods. | | Same operation key, changed body | `1013` | Retry the original payload or use a new key for a new operation. | | Cross-tenant support identifier | Resource-specific `*001` | Treat it exactly like a missing resource; do not probe ownership. |