When an Account Center API call fails, the gateway returns a non-2xx HTTP status with a JSON error body. Use this page to identify what went wrong and how to recover.Documentation Index
Fetch the complete documentation index at: https://uqpay-ecc4f4d8.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Error response format
The Account Center API uses a single response envelope for errors:| Field | Meaning |
|---|---|
code | Numeric status. In most cases equals the HTTP status on the response. 400 for validation and business-rule errors, 403 for authentication / authorization failures, 404 for unknown routes, 405 for unsupported HTTP methods, 500 for infrastructure failures in the idempotency middleware. |
message | Human-readable description. Safe to log, not safe to surface verbatim to end-users. Branch on the message to distinguish cases within a given code. |
type field and no string error codes — everything is a numeric code plus a message.
Error codes overview
code | HTTP | When it appears |
|---|---|---|
400 | 400 | Validation failure, business-rule violation, malformed JSON, or any handler-level error. Branch on message for the specific case. |
403 | 403 | Authentication failure — missing, malformed, or expired access token; IP allow-list violation; missing client id claim. |
404 | 404 | The request path does not match any registered route. |
405 | 405 | The request method is not bound for this path. |
500 | 500 | Internal failure in the idempotency middleware (Redis / DB). Safe to retry with the same X-Idempotency-Key. |
Common errors
These can appear on any authenticated endpoint regardless of the resource.code | Message | What to do |
|---|---|---|
403 | Authorization error | Send an x-auth-token header carrying a non-expired access token obtained from Access Token. Re-mint the token if it has expired and retry. |
403 | x-client-id or email cannot be empty | Supply the x-client-id header with the same client_id used when you called Access Token. Do not omit it on authenticated calls. |
400 | IP not allowed | Ensure the request originates from an IP on the developer key’s allow-list. Update the allow-list in the UQPAY dashboard, or retry from a permitted address. |
400 | Request parameters invalid | Re-check your request body and query parameters against the endpoint’s API Reference — one or more required fields are missing or have the wrong type. |
400 | (varies — raw JSON binding / validator error text, e.g. Field 'X' is required, Invalid type for field 'X') | Read the message verbatim: it names the offending field and the validator rule it failed. Fix that field in the request body and retry. |
400 | access token err | Your x-auth-token is missing, malformed, or its JWT claims cannot be resolved to an entity. Mint a fresh token from Access Token and retry. |
400 | Idempotency key error | Supply an X-Idempotency-Key that is either a RFC-4122 UUID (for accounts created after 2024-08-15) or a 1–36 character string (for older accounts). Do not reuse expired keys. |
400 | Idempotency key auth error | The X-Idempotency-Key you sent has already been used by a different entity. Generate a new UUID per request, or retry using the original caller’s credentials. |
400 | Idempotency endpoint error | The X-Idempotency-Key was previously used on a different endpoint. Use a fresh key for each distinct endpoint, or retry against the original endpoint. |
400 | Request is processing, please try again later. (body code reads 200) | The original request is still executing. Wait a few seconds, then retry with the same X-Idempotency-Key to fetch the cached response. |
500 | An internal error occurred, please try again later (no code field in body) | A transient failure in the idempotency middleware (Redis / DB). Safe to retry with the same X-Idempotency-Key — if it keeps happening, contact UQPAY support. |
401 | Invalid authorization header (emitted as { "error": ... }) | Your x-auth-token starts with Bearer but is not a valid Bearer <token> pair. Either drop the Bearer prefix and send the raw JWT, or send exactly Bearer <jwt> with a single space. |
404 | Not found | Check the request path and HTTP method against the API Reference — the route you called is not registered on the gateway. |
405 | Method not allowed | The path is valid but you used the wrong HTTP method. Check the verb (GET / POST / PUT / DELETE) in the API Reference for that endpoint. |
Resource errors
Authentication
Endpoints
Endpoints
Access Token
POST /v1/connect/token has its own handler (AccessHandler.AccessToken) that emits only flat HTTP 400 responses — including for auth-adjacent failures such as expired or unknown API keys. The message tells you the specific case.
code | Message | Typical endpoints | What to do |
|---|---|---|---|
400 | Request parameters invalid | Access Token | Include both client_id and api_key as non-empty form fields (or JSON body fields) in your POST to /v1/connect/token. |
400 | Invalid client id | Access Token | Verify the client_id value matches a developer credential in your UQPAY dashboard. Copy it again to rule out stray whitespace or typos. |
400 | Invalid api key | Access Token | Verify the api_key matches the key paired with your client_id. Regenerate the key pair from the dashboard if the current key has been rotated. |
400 | Api key expired | Access Token | Your api_key has passed its validity window. Generate a fresh key pair from the UQPAY dashboard and update your integration. |
400 | Entity config not exist | Access Token | The entity that owns this client_id has no configured access profile. Contact your UQPAY solutions engineer to provision the entity configuration. |
400 | Api trading status error | Access Token | The developer key is disabled or the entity’s trading status is not active. Check the key’s status in the UQPAY dashboard, or contact UQPAY support to reactivate. |
400 | IP not allowed | Access Token | The caller IP is not on the allow-list configured for this api_key. Add the IP in the UQPAY dashboard, or retry from a permitted address. |
400 | Create access token error | Access Token | An internal signing / persistence failure occurred. Retry after a short delay; if the error persists, contact UQPAY support. |
Entities
Endpoints
Endpoints
Create Account · Create SubAccount · List Connected Accounts · Retrieve Account · Get Additional Documents
Create Account and Create SubAccount). All are emitted as flat HTTP 400 with the exact validator message in message. Representative cases are listed below; branch on message for programmatic handling.
code | Message | Typical endpoints | What to do |
|---|---|---|---|
400 | access token err | Any endpoint in this group | Your x-auth-token is missing or its claims cannot be resolved to a caller entity. Mint a fresh token from Access Token and retry. |
400 | entity not exist | Retrieve Account | Verify the {id} path parameter refers to an account your credentials can see. Use List Connected Accounts to enumerate accessible accounts. |
400 | unable to retrieve the corresponding entityinfo | Retrieve Account | The {id} exists but is not linked to your calling entity as a parent / child. Confirm the account belongs under your hierarchy before retrieving it. |
400 | entity not found | Retrieve Account | The {id} does not resolve to any account record. Double-check the ID — it should be one returned by List Connected Accounts. |
400 | (field validation — varies, e.g. Legal business name in English is required, Country or territory is required, Invalid phone number format, Individual must be over 18 years old, Job title is required and must be one of director, beneficial_owner, beneficial_owner_and_director, authorized_representative, Entity type is required and must be one of COMPANY, INDIVIDUAL) | Create Account · Create SubAccount | Read the message — it names the offending field and rule. Fix that field in the business_details / identities / owners section of the request and retry. |
400 | The country is not allowed to be used for onboarding | Create Account · Create SubAccount | The country in business_details.country or identities[].country is not on UQPAY’s supported list. Pick a supported jurisdiction or contact UQPAY support to check expansion plans. |
400 | The country is a sanctioned country | Create Account · Create SubAccount | UQPAY cannot onboard accounts in sanctioned jurisdictions. No retry will succeed — do not retry with the same country. |
400 | please check whether the master account has opened the corresponding service | Create Account · Create SubAccount | Your master account is not entitled to the product (Acquiring / Banking / Issuing) implied by the request. Contact your UQPAY solutions engineer to enable the service. |
400 | please check whether the master account has opened the create sub account service | Create SubAccount | Your master account lacks the sub-account provisioning entitlement. Contact UQPAY to enable it before retrying. |
400 | please completed the verification and activate your account first | Create Account · Create SubAccount | Your master account is still pending KYC / activation. Finish onboarding for the master account before creating sub-accounts. |
400 | only banking can create individual account | Create Account · Create SubAccount | Individual (non-company) accounts can only be created under a Banking product. Change the entity type to COMPANY, or request Banking provisioning for individual onboarding. |
400 | failed to retrieve account configuration | Create Account · Create SubAccount | An internal lookup failed. Retry after a short delay; if it persists, contact UQPAY support. |
400 | failed to retrieve parent account related info | Create SubAccount | An internal lookup on the parent account failed. Verify the caller token belongs to a valid master account and retry. |
400 | failed to check sub account limit | Create SubAccount | An internal limit-check failed. Retry after a short delay; if it persists, contact UQPAY support. |
400 | (varies — e.g. same UEN sub account limit reached, current: 10, max: 10) | Create SubAccount | You have reached the maximum number of sub-accounts allowed under a shared UEN / registration number. Consolidate existing sub-accounts or contact UQPAY to raise the limit. |
400 | Company info, address, and ownership details are required when Inherit is false | Create SubAccount | Either set inherit: true to reuse the parent’s KYC data, or supply the full business_details, address, and owners blocks. |
400 | Please check that you have correctly specified inherit | Create SubAccount | The inherit flag is inconsistent with the rest of the payload. Set inherit: true for inherited setup, or false with complete company details. |
400 | representatives is empty | Create Account · Create SubAccount | Supply at least one entry in the representatives / identities array — UQPAY requires a named authorized representative. |
400 | representative identification documents are empty | Create Account · Create SubAccount | Attach identification documents (passport / national ID) for each representative via Upload A File, then reference the returned file IDs in the representative record. |
400 | one representative must be an applicant | Create Account · Create SubAccount | Mark exactly one representative as the applicant (is_applicant: true or role authorized_representative) in the request. |
400 | Failed identification, at least one beneficiary submitted front and back identification photos and face photos | Create Account · Create SubAccount | At least one beneficial owner needs front ID, back ID, and a face photo uploaded via Upload A File. Reference the three file IDs on that owner record. |
400 | document ID already exists | Create Account · Create SubAccount | The identification number you submitted is already tied to another entity at UQPAY. Use the correct entity or contact UQPAY support to resolve the collision. |
400 | check that you have submitted the necessary documents | Create Account · Create SubAccount | One or more required documents are missing — the set varies by entity type and country. Consult your UQPAY onboarding checklist and upload the missing items via Upload A File. |
400 | businessDetails is nil | Create Account · Create SubAccount | The request body is missing the business_details object. Include it (or, for sub-accounts, set inherit: true to inherit from parent). |
400 | entityBasicVersion is nil | Create Account · Create SubAccount | Internal state issue on the parent record. Contact UQPAY support with the request ID — retrying without changes is unlikely to succeed. |
400 | entity is nil | Create Account · Create SubAccount | The caller entity could not be resolved server-side. Re-mint your access token from Access Token and retry; if it persists, contact UQPAY support. |
400 | server error | Create Account · Create SubAccount | An internal failure occurred. Safe to retry after a short delay; if it persists, contact UQPAY support with the request ID. |
400 | (generic persistence failure — raw DB or marshal error text wrapped by the service layer) | Create Account · Create SubAccount | Capture the exact message and contact UQPAY support — the wrapped error text identifies which persistence step failed. Retrying without changes is unlikely to succeed. |
Files
Endpoints
Endpoints
Upload A File · Get File Download Links
code | Message | Typical endpoints | What to do |
|---|---|---|---|
400 | access token err | Upload A File · Get File Download Links | Your x-auth-token is missing or cannot be resolved. Mint a fresh token from Access Token and retry. |
400 | x-on-behalf-of value err | Upload A File · Get File Download Links | The x-on-behalf-of header must be the entity ID of a sub-account under the calling master account. Verify it via List Connected Accounts, or omit the header to act on the master account itself. |
400 | Request parameters invalid | Upload A File · Get File Download Links | Check the required fields — for Upload A File, send the multipart file part; for Get File Download Links, send the file_ids array in the JSON body. |
400 | Parse file failed | Upload A File | The multipart form could not be parsed. Confirm the request uses Content-Type: multipart/form-data, includes a boundary, and the file field is named file. |
400 | File size error (threshold: 30 MiB) | Upload A File | The file exceeds 30 MiB. Compress or split the file before uploading. |
400 | invalid file name, please check the file | Upload A File | The uploaded file has an empty or unsupported filename. Provide a file with a valid name and a supported extension (.jpeg, .png, .jpg, .doc, .docx, .pdf). |
400 | invalid file type, please check the file, only support jpeg, png, jpg, doc, docx, pdf | Upload A File | Convert the file to one of the supported formats (JPEG / PNG / JPG / DOC / DOCX / PDF) and retry. |
400 | unsupported file type | Upload A File | The file’s MIME type is not in the supported list. Re-export as JPEG / PNG / PDF / DOC / DOCX and retry. |
400 | (varies — e.g. file validation failed: mime type mismatch) | Upload A File | Read the message — it names the validation rule that failed (commonly MIME type does not match the extension). Re-export the file cleanly and retry. |
400 | open file occur error, please check the file | Upload A File | The server could not open the uploaded file — usually because it is truncated or corrupt in transit. Re-select the source file and retry the upload. |
400 | read file occur error, please check the file | Upload A File | The uploaded file stream was unreadable. Retry with the original source file; if it persists, the file may be corrupt. |
400 | seek file error | Upload A File | Internal I/O error while processing the upload. Retry the request; if it persists, contact UQPAY support. |
400 | upload file occur error, please contact our team | Upload A File | Cloud storage write failed. Retry after a short delay; if it persists, contact UQPAY support with the request ID. |
400 | Query data error | Get File Download Links | One or more file_ids do not exist or are not visible to your entity. Verify the IDs — they must be returned by a prior Upload A File call your credentials can access. |
Idempotency
Endpoints
Endpoints
Create Account · Create SubAccount · Upload A File
POST that carries a body. It short-circuits before the handler executes when a replay is detected.
code | Message | Typical endpoints | What to do |
|---|---|---|---|
400 | Idempotency key error | Create Account · Create SubAccount · Upload A File | Supply an X-Idempotency-Key that is a RFC-4122 UUID (for entities created after 2024-08-15) or a 1–36 character string (for older entities). Do not reuse keys older than 24 hours. |
400 | Idempotency key auth error | Create Account · Create SubAccount · Upload A File | The X-Idempotency-Key is already cached against a different entity. Generate a new UUID per request, or retry with the original caller’s credentials. |
400 | Idempotency endpoint error | Create Account · Create SubAccount · Upload A File | The same X-Idempotency-Key was previously used on a different endpoint. Use a distinct key per endpoint, or retry against the original endpoint. |
200 | Request is processing, please try again later. (HTTP status is 400, body code is 200) | Create Account · Create SubAccount · Upload A File | The original request is still running. Wait a few seconds and retry with the same X-Idempotency-Key — the cached response will be returned once processing completes. |
| (none) | An internal error occurred, please try again later (HTTP 500, body has no code field) | Create Account · Create SubAccount · Upload A File | Transient infrastructure failure in the idempotency layer. Retry with the same X-Idempotency-Key; if it persists, contact UQPAY support. |