Error codes

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.

Error response format

The Account Center API uses a single response envelope for errors:

{
  "code": 400,
  "message": "Legal business name in English is required"
}

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`.

There is no 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

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

Create Account · Create SubAccount · List Connected Accounts · Retrieve Account · Get Additional Documents

Validation on account-creation requests is extensive (over 80 distinct field-level messages across 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

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

Create Account · Create SubAccount · Upload A File

The idempotency middleware runs on every 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.

Getting Started

Authentication

Account Management

Webhooks

Reference

Error response format

Error codes overview

Common errors

Resource errors

Authentication

Entities

Files

Idempotency

​Error response format

​Error codes overview

​Common errors

​Resource errors

​Authentication

​Entities

​Files

​Idempotency

Error response format

Error codes overview

Common errors

Resource errors

Authentication

Entities

Files

Idempotency