General API Error Codes

These error codes are consistent across the API.

Authentication and account errors

Error	Code	Error message
INVALID_ACCOUNT	AUTH-0001	Your account does not have the right permission to login to this portal. Please Apply for an Enterprise Account.
INVALID_CREDENTIALS	AUTH-0002	Incorrect auth details. Also returned as `<operation> requires account type CONSUMER` (or `BUSINESS`). See below.
PHONE_NUMBER_NOT_FOUND	AUTH-0003	Unable to find provided phone number or phone number it is not verified. Please select different method or contact customer support.
INVALID_PHONE_NUMBER	AUTH-0004	Invalid phone number.
INVALID_2FA_TOKEN	AUTH-0005	Access denied or expired.
INCORRECT_AUTH_CODE	AUTH-0006	Auth code provided is incorrect, please check and re-enter received code and try again.
UNABLE_TO_SEND_AUTH_CODE	AUTH-0007	Sorry, we were unable to send the auth code, please try again or contact customer support.
INVALID_USER_ACCESS	AUTH-0008	Invalid user access.
INVALID_PASSWORD	AUTH-0009	The provided password is not valid.
NO_PIN_EXISTS	AUTH-0010	There is no passcode set on the user, please create one instead.
PIN_ALREADY_SET	AUTH-0011	There is already a passcode set on the user, please reset instead.
INVALID_PIN_CODE	AUTH-0012	The provided passcode does not match our records, please try again or reset your passcode.
SOCIAL_UNABLE_TO_LOGIN	AUTH-0013	Unable to login with your social account. Please verify your credentials and try again or contact customer support.
UNABLE_TO_CREATE_PIN	AUTH-0014	Unable to create new pass-code, please try again or contact customer support.
UNABLE_TO_CHECK_PIN	AUTH-0015	Unable to check pass-code, please try again or contact customer support.
UNABLE_TO_UPDATE_PIN	AUTH-0016	Unable to update pass-code, please try again or contact customer support.
UNABLE_TO_RESET_PIN	AUTH-0017	Unable to reset pass-code, please try again or contact customer support.
TRADITIONAL_UNABLE_TO_LOGIN	AUTH-0018	Unable to login with your account. Please verify your credentials and try again or contact customer support.
INVALID_JWT	AUTH-0019	Invalid JWT Token!
UNABLE_TO_RESEND_2FA	AUTH-0020	Unable to re-send 2FA!
UNSUPPORTED_PHONE_NUMBER	AUTH-0021	Provided number is not a valid mobile phone number! Please contact support for more details.
REGISTRATION_NOT_ALLOWED	AUTH-0022	Registration not allowed, please contact customer support! `registerUser` isn’t enabled on this application.
UNABLE_TO_CHANGE_PASSWORD	AUTH-0023	Unable to change password. Please try again or contact customer support.
UNVERIFIED_PHONE_NUMBER	AUTH-0024	Your phone number requires verification. Please contact support.
UNSUCCESSFUL_REGISTRATION	AUTH-0025	Please try again again or contact support.
REGISTRATION_PHONE_TAKEN	AUTH-0026	The phone number you chose is already in use.
REGISTRATION_EMAIL_TAKEN	AUTH-0027	The email address you chose is already in use.
UNABLE_TO_RESET_PASSWORD	AUTH-0028	Unable to reset password.
SECURITY_CODE_EXPIRED	AUTH-0029	Your 6-digit security code has expired. Please resend a new code.
APPLICATION_INACTIVE	AUTH-0030	Application `<app_id>` is not active (current status: `PERSONAL` or `REVIEW`). See below.
INVALID_SCOPE	AUTH-0031	The requested scopes must be granted by the user first.

Troubleshooting the common ones

AUTH-0030: application is not active

Application 4bfebaf0-… is not active (current status: PERSONAL)

current status is the application’s status, not your account type. New applications can only act for the developer who created them until Fluz moves them to ACTIVE. Switching or converting accounts won’t fix it.

Check the application type. Apps made with Create new app can only act for their developer. To act for other users, create one from Templates → OAuth Integration.
Ask Fluz to activate it. Send the application name or ID to your Fluz contact. Activation is per environment.

Don’t retry automatically; this is a configuration problem. See How accounts work.

AUTH-0002: requires account type

Insufficient permissions: getBusinessCategories requires account type CONSUMER

The operation needs a token for a different account type. Every token is minted for one accountId: a personal account gives a CONSUMER token, and a business account gives a BUSINESS token. Mint a new token with the same userId and the other accountId (Get Accounts lists them), then retry. The operations with a fixed requirement are listed in How accounts work.

AUTH-0022: registration not allowed

registerUser must be enabled on your application by Fluz, separately in staging and live. Contact your account manager. Don’t retry.

AUTH-0026 / AUTH-0027: already in use

The person already has a Fluz account. This isn’t a failure: route them to the OAuth grant flow so they can authorize your app on the account they already have.

Address errors

Address fields are validated across several flows. Constraints differ by context: for example, virtual card and bank account addresses are US-only, while business legal addresses may be international. For formatting rules and worked examples, see Address Formatting Requirements.

Error	Code	Applies to	Error message
INVALID_BILLING_ADDRESS	VC-0025	Virtual card issuance (billing address)	The billing address could not be verified. It must be a deliverable US address (no PO boxes) with a matching city, state, and ZIP.
InvalidBusinessLegalAddress	BS-0002	Business registration (KYB)	Business legal address is incorrect.
InvalidOwnerInformation	BS-0003	Business registration (KYB)	One or more owner details are incorrect (includes the owner’s US-based address).

Missing or malformed address fieldsA missing required field, or an invalid value inside an address object, is returned as a general argument error rather than one of the address codes above. On virtual card calls that’s ARG-0001; on business registration it’s AR-0001 or AR-0002.

Next steps

Errors reference

The error envelope shape, domain prefixes, and how to troubleshoot with request IDs.

Address formatting

Formatting rules and worked examples for avoiding the address errors above.

Want to learn more? Contact us at partnerships@fluz.app. Speak with our experts for more info or to request a demo.

Developers

Recipes

General API Error Codes

Authentication and account errors

Troubleshooting the common ones

AUTH-0030: application is not active

AUTH-0002: requires account type

AUTH-0022: registration not allowed

AUTH-0026 / AUTH-0027: already in use

Address errors

Next steps

Errors reference

Address formatting

​Authentication and account errors

​Troubleshooting the common ones

​AUTH-0030: application is not active

​AUTH-0002: requires account type

​AUTH-0022: registration not allowed

​AUTH-0026 / AUTH-0027: already in use

​Address errors

​Next steps

Errors reference

Address formatting

Authentication and account errors

Troubleshooting the common ones

AUTH-0030: application is not active

AUTH-0002: requires account type

AUTH-0022: registration not allowed

AUTH-0026 / AUTH-0027: already in use

Address errors

Next steps