Troubleshooting
This section helps you identify and resolve common issues that may occur when integrating with our API.
Common Errors
1. 401 Unauthorized
Cause:
The access token, refresh token, or credentials are missing, expired, or invalid.
| Code | Message | Possible Fixes |
|---|---|---|
40120 | Invalid or missing access token. | Ensure that the Authorization header is included in your request, formatted as:Authorization: Bearer <access_token> |
40121 | Invalid or missing refresh token. | Verify that the refresh token is valid and has not been revoked. Obtain a new one by re-authenticating. |
40122 | Session expired. | The user session has timed out. Prompt the user to sign in again. |
40123 | Token expired. | Refresh the access token using the refresh token endpoint before retrying the request. |
40124 | User not authenticated. | Ensure the user is logged in and that valid credentials are passed during authentication. |
40125 | Authentication failed. | Check your client credentials. Ensure they match the configured values in your environment. |
2. 400 Bad Request
Cause: The request was malformed or contained invalid data. Check the request body, headers, or parameters before retrying.
| Code | Message | Possible Fixes |
|---|---|---|
40010 | Weak password. | Use a stronger password that meets complexity rules (min length, upper/lowercase, number, special character). |
40021 | Invalid POS ID. | Verify that the provided POS ID exists and is registered in the system. |
40022 | Invalid merchant ID. | Ensure that the merchant ID matches the account credentials used for the request. |
40023 | Invalid device ID. | Confirm the device is correctly registered and paired with the POS account. |
40024 | Invalid API Version. | Check the apiVersion parameter and ensure it matches the supported version. |
40026 | Invalid signature. | Ensure the signature is generated correctly using your private key and includes all required fields. |
40027 | Invalid datetime. | Use a valid ISO 8601 datetime format (e.g., yyyyMMddHHmmss). |
40028 | Currency is required. | Include the currency field in your request body or parameters. |
40029 | Invalid transaction status. | Use a different transaction with a valid status. |
40030 | Invalid request type. | Ensure the request type value is recognized by the API. |
40031 | Invalid or missing parameters. | Double-check required parameters against the API documentation and correct data types. (refer: API Reference Section) |
40032 | Invalid terminal response parameters. | Verify the terminal response format matches the expected schema. |
40033 | Password confirmation failed. | Ensure password and confirmPassword fields match exactly. |
40034 | Old and new password must not be same. | Choose a new password different from the current one. |
40035 | Invalid reset key. | Check that the password reset key provided in the email is valid and corresponds to the requesting user. |
40036 | Invalid activation key. | Confirm the activation key is correct and not already used. |
40037 | Reset key has expired. | Request a new password reset link or key. |
40038 | Activation key has expired. | Generate a new activation key through the activation process. |
3. 403 Forbidden
Cause: The client is authenticated but lacks permission to perform the requested operation.
| Code | Message | Possible Fixes |
|---|---|---|
40310 | User not authorized. | Ensure the authenticated user has the required permissions or roles. |
40311 | Login failed, this account is pending activation. | Complete the account activation process before attempting to log in. |
40312 | Login failed, this account is currently suspended. | Contact support to re-enable the account. |
40313 | Login failed, this account is permanently deleted. | Use a different account or register a new one. |
40314 | Active session exists. | Log out from other sessions before initiating a new one. |
40315 | Permission check failed. | Verify your API key or token has permission for the requested resource. |
40316 | Unbind terminal failed. | Ensure terminal is in a valid state before unbinding and that correct IDs are supplied. |
40317 | Unknown terminal. | Confirm the terminal unique ID exists and is linked to the POS account. |
40320 | Invalid signature. | Recalculate your request signature using the correct secret key. |
40321 | Invalid checksum. | Validate the checksum formula and compare it with the server’s expected value. |
40399 | Channel declined. | The payment channel rejected the transaction. Try another payment method or contact support. |
4. 404 Not Found
Cause:
The requested resource or endpoint could not be found.
| Code | Message | Possible Fixes |
|---|---|---|
40410 | Transaction not found. | Verify the transaction ID or reference number is correct and pointed to the right terminal. |
40420 | Account not found. | Check the account ID and ensure it exists in the system. |
5. 408 Request Timeout
Cause:
The request took too long to complete due to network or terminal latency.
| Code | Message | Possible Fixes |
|---|---|---|
40810 | Request timed out. | Retry the request after a few seconds. Check your network connection and server response time. |
40811 | Terminal timeout. | Ensure the terminal is online and properly connected before retrying. |
6. 422 Unprocessable Entity
Cause:
The server understood the request but couldn’t process it due to business logic validation failure.
| Code | Message | Possible Fixes |
|---|---|---|
42210 | Operation cancelled by the terminal. | Retry only if user confirmation is expected. Do not force retries automatically. |
42211 | Transaction declined. | Check the terminal or payment channel response for decline reasons. |
7. 429 Too Many Requests
Cause:
The client has sent too many requests in a short period or a duplicate transaction was detected.
| Code | Message | Possible Fixes |
|---|---|---|
42910 | Terminal busy. | Wait a few seconds before retrying. Avoid sending concurrent requests to the same terminal. |
42920 | Duplicated request. | Ensure each transaction includes a unique signature, or retry the request after a few seconds. |
42930 | Login failed, this account is temporarily locked due to multiple failed login attempts. | Wait for the lockout duration to expire or reset your password. |
8. 500 Internal Server Error
Cause:
An unexpected condition occurred on the server.
| Code | Message | Possible Fixes |
|---|---|---|
500 | Internal server error. | Retry after a short delay. If persistent, report to Fiuu Support with request details and timestamp. |
50010 | SDK server error. | Check if the SDK version is up-to-date and compatible with the current API. |
8. 503 Service Unavailable
Cause:
The API or dependent service (terminal, printer, or channel) is temporarily unavailable.
| Code | Message | Possible Fixes |
|---|---|---|
50310 | Terminal not connected. | Ensure the terminal is powered on and connected to the network. |
50311 | No terminal response. | Retry the operation. If issue persists, check terminal logs and connectivity. |
50312 | Terminal error. | Check the terminal error message or contact support if the issue continues. |
50313 | Printer unavailable. | Use a terminal that supports printer functionality. |
50320 | Payment method unavailable. | Use a supported payment method. |
50321 | Payment channel unavailable. | Ensure the payment channel is enabled for your merchant account. |
Additional Tips
- Always log the full response (status code + message) for debugging.
- Enable verbose or debug mode in your application during testing.
- Keep your API library or application version up-to-date.
- For persistent issues, contact the our support team with:
- Full request URL
- Timestamp
- Merchant ID, POS ID, Device ID and Transaction ID (if applicable)
- Request and response body (redact sensitive info)