Troubleshooting Guide

This guide provides solutions to common issues you might encounter when working with the Service API, including error code explanations, troubleshooting steps, and logging information.

1. Error Codes

The Service API uses a consistent set of error codes across both SOAP and REST interfaces.

1.1. Common Error Codes

Code Description Troubleshooting Steps

201

No device

Verify the device serial number is correct and the device exists in the ACS

202

No DB

Database connection issue - check database configuration and connectivity

203

Incorrect request structure

Check your request format against the API documentation

204

General error

Review logs for more specific details about the failure

205

No ACS

ACS connection issue - verify ACS URL and credentials

401

Authentication failure

Check your API credentials and ensure they have not expired

403

Authorization error

Verify the user has appropriate permissions for the requested operation

404

Resource not found

Ensure the requested resource (device, service, etc.) exists

409

Conflict

Operation cannot be performed in current state - check business rules

500

Internal server error

Review server logs for detailed error information

1.2. SOAP-Specific Errors

Code Description Troubleshooting Steps

SOAP-ENV:Client

Client-side error

Check your request format and parameters

SOAP-ENV:Server

Server-side error

Server encountered an unexpected error - check logs

SOAP-ENV:MustUnderstand

Required header missing

Add the required SOAP header to your request

SOAP-ENV:VersionMismatch

SOAP version mismatch

Ensure you’re using the correct SOAP version

1.3. REST-Specific Status Codes

Status Description Troubleshooting Steps

400

Bad Request

Check request format and parameters for errors

401

Unauthorized

Authentication failed - verify credentials

403

Forbidden

User lacks permission for the requested operation

404

Not Found

Resource does not exist

405

Method Not Allowed

The HTTP method is not supported for this endpoint

409

Conflict

Business rule violation - operation cannot be performed

429

Too Many Requests

Rate limit exceeded - slow down request rate

500

Internal Server Error

Server-side error - check logs for details

503

Service Unavailable

Service is temporarily unavailable - try again later

2. Common Issues

2.1. Authentication Problems

2.1.1. SOAP Authentication Failures

Issue: SOAP requests fail with authentication errors.

Solution: * Ensure WS-Security headers are correctly formatted * Verify username and password are correct * Check if the account is locked or disabled

2.1.2. JWT Token Issues

Issue: JWT token is rejected.

Solution: * Verify the token has not expired * Ensure you’re using the correct token format (Bearer) * Check if the token has been revoked * Request a new token

2.2. Connection Problems

2.2.1. Cannot Connect to Service API

Issue: Unable to establish connection to the Service API.

Solution: * Verify the Service API server is running * Check network connectivity * Ensure firewall rules allow the connection * Verify DNS resolution for the Service API hostname

2.2.2. Timeout Errors

Issue: Requests time out before receiving a response.

Solution: * Increase client timeout settings * Check if the Service API is under heavy load * Verify the ACS is responding properly * Check network latency between components

2.3. Operation Failures

2.3.1. Device Not Found

Issue: API returns "No device" error.

Solution: * Verify the device serial number is correct * Check if the device exists in the ACS * Ensure the device has communicated with the ACS recently

2.3.2. Parameter Update Failures

Issue: Cannot update device parameters.

Solution: * Verify the parameter exists on the device * Check if the parameter is writable * Ensure the new value is valid for the parameter type * Verify the device is online and reachable

2.3.3. Speed Test Failures

Issue: Speed test operation fails.

Solution: * Verify the device supports speed test diagnostics * Check if the device is online * Ensure the ACS has appropriate diagnostic URLs configured * Increase the operation timeout for long-running tests

3. Logging

3.1. Log Locations

  • Container stdout/stderr: Access via docker logs <container-name>

  • Volume-mounted logs: /app/logs/ (requires mount like -v /usr/local/service-api/logs:/app/logs)

  • Centralized logging: Configure log driver for external log aggregation

3.2. Runtime Log Level Management

The application supports changing the log level at runtime without restarting the container, using Spring Boot Actuator.

Level What is logged

ERROR

Critical errors only (lost connection to ACS/DB)

WARN

Business errors (device not found, invalid parameter) — without stack trace

INFO

Key operations (startup, authorization, main actions)

DEBUG

Detailed diagnostics + stack traces for business errors

In production use INFO. Switch to DEBUG temporarily when investigating issues — business errors will include full stack traces.
View current log level (GET)
curl http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.apiservice
Response example (HTTP 200)
{
    "configuredLevel": "DEBUG",
    "effectiveLevel": "DEBUG"
}
Switch to INFO (POST)
curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.apiservice \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "INFO"}'
Switch to DEBUG (POST)
curl -X POST http://<host>:8080/iot-webservice/actuator/loggers/com.friendly.apiservice \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel": "DEBUG"}'
All POST requests return HTTP 204 No Content with an empty body — this is the expected success response. To verify the change, use the GET request above.

To change the log level persistently (survives container restart), set LOGGING_LEVEL_COM_FRIENDLY_APISERVICE in the environment file (.env.mysql or .env.oracle):

# Values: ERROR, WARN, INFO, DEBUG
LOGGING_LEVEL_COM_FRIENDLY_APISERVICE=INFO

3.3. Host Volume Permissions (SELinux / rootless / NFS/CIFS)

Symptom: Logs are visible in container stdout, but files are not created in the host logs/ directory.

Checks and fixes:

  • SELinux: relabel the mount with :Z (or :z for shared use): -v /usr/local/service-api/logs:/app/logs:Z

  • rootless Docker: container user may not be able to chown; pre-create writable directory on host: mkdir -p /usr/local/service-api/logs && chmod 775 /usr/local/service-api/logs

  • NFS/CIFS mounts: ownership change may be blocked by storage settings; ensure write permission is granted by mount options/export policy for the container process

  • Verify mount and effective permissions: docker inspect service-api --format '{{json .Mounts}}' and docker exec service-api sh -c 'id; ls -ld /app/logs; touch /app/logs/.perm_test && rm /app/logs/.perm_test'

# View container logs
docker logs service-api

# Follow logs in real-time
docker logs -f service-api

# View last 100 lines
docker logs --tail 100 service-api

4. Diagnostic Tools

4.1. Health Endpoint

The Service API provides a health endpoint to check system status:

curl -X GET "http://example.com/iot-webservice/actuator/health"

Sample response:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    },
    "acsConnection": {
      "status": "UP"
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500107862016,
        "free": 325889617920,
        "threshold": 10485760
      }
    }
  }
}

4.2. Metrics Endpoint

To view operational metrics:

curl -X GET "http://example.com/iot-webservice/actuator/metrics"

For specific metrics:

curl -X GET "http://example.com/iot-webservice/actuator/metrics/http.server.requests"

4.3. Environment Information

To check environment configuration:

curl -X GET "http://example.com/iot-webservice/actuator/env"

5. Contacting Support

If you cannot resolve an issue using this guide, contact Friendly Technologies support:

When contacting support, please provide:

  • Service API version

  • Detailed error message

  • Relevant log entries

  • Steps to reproduce the issue

  • Any recent changes to your environment