Troubleshooting 101: A Comprehensive Guide to Addressing Toll SDK Issues
Dive into this essential runbook tailored for Toll SDK users. From common hiccups to intricate challenges, we’ve got you covered, ensuring smooth sailing with your Toll SDK experience.
Introduction
This runbook helps developers and support teams to identify, understand, and resolve frequently encountered issues with the TollGuru SDK and its endpoints. By using this manual as a guide, users can quickly address issues, ensuring the SDK runs smoothly and delivers accurate results.
You may encounter two types of issues:
- SDK-specific (deployment / in use)
- SDK API Requests and responses
SDK Setup Issues
For any issues with installing the TollGuru SDK, we recommend reading the final section of the following Medium article: Deploy Toll SDK on Your AWS Cloud: A Comprehensive Setup Guide.
To configure and deploy the TollGuru SDK on your AWS cloud environment, refer to this comprehensive setup guide, which offers clear instructions and troubleshooting advice. It covers a variety of setup-related topics, such as AWS credentials, API endpoints, and application integration. If you encounter issues during the SDK setup phase, this guide should be your go-to resource for resolving them effectively.
For detailed steps on testing the TollGuru SDK, please consult this article: Testing Toll SDK deployed on your AWS Cloud.
Additionally, if you’re looking to enhance the security measures of your deployed TollGuru SDK, we highly recommend going through this comprehensive guide on ramping up security: Enhancing Security for Toll SDK on AWS Infrastructure.
Error categories for API requests and responses
The three main categories of errors that can occur when interacting with the SDK are ROUTING_ERROR, INPUT_ERROR, TOLLING_ERROR, and SERVICE_ERROR. Each category refers to a different aspect of issues and has different error messages associated with it.
ROUTING_ERROR:
When issues arise during route creation, it typically indicates difficulties in mapping the provided GPS or polyline data to form a complete and accurate route.
{
"code": "ROUTING_ERROR",
"status": 500,
"value": "Unable to generate a route for the provided GPS tracks"
}Resolution:
- Ensure that the GPS data contains precise location coordinates to avoid deviations from the intended path.
- Make sure that the GPS data covers the entire route without any gaps or missing segments.
- Maintain a consistent recording interval for the GPS data to prevent inaccuracies when connecting data points.
INPUT_ERROR:
These categories of errors happen when the request to an SDK endpoint is made with invalid input.
Missing Polyline or Path
{
"status": 400,
"code": "INPUT_ERROR",
"value": "Either polyline or path must be specified"
}- Resolution: Ensure that the request body contains either a polyline or a path.
Missing locTimes
{
"status": 400,
"code": "INPUT_ERROR",
"value": "Missing locTimes. Length should be greater than 2"
}- Resolution: Ensure that the request body contains locTimes and make sure that its length is greater than 2.
Invalid locTimes Length
{
"status": 400,
"code": "INPUT_ERROR",
"value": "Invalid locTimes: Length should be greater than 2"
}- Resolution: Ensure that locTimes has a length greater than 2.
Unsupported Vehicle Type
{
"status": 400,
"code": "INPUT_ERROR",
"value": "2BxlesAuto is not a valid vehicle type for region Australia. For list of supported vehicle types by region, please visit: https://github.com/mapup/tollguru_vehicle_coverage/wiki/Vehicle-types-supported-by-TollGuru"
}- Resolution: Confirm that the vehicle type provided is supported in the specified region. For more information, see the supported vehicle types.
Invalid Fuel Cost
{
"status": 400,
"code": "INPUT_ERROR",
"value": "Fuel cost should be greater than zero"
}- Resolution: Ensure that the fuel cost is a valid number greater than zero.
Invalid City Fuel Efficiency
{
"status": 400,
"code": "INPUT_ERROR",
"value": "City fuel efficiency should be greater than zero"
}- Resolution: Ensure that the city fuel efficiency is a valid number greater than zero.
Invalid Highway Fuel Efficiency
{
"status": 400,
"code": "INPUT_ERROR",
"value": "Highway fuel efficiency should be greater than zero"
}- Resolution: Ensure that the highway fuel efficiency is a valid number greater than zero.
TOLLING_ERROR
The tolling error arises when the system encounters difficulties in calculating toll fees for the specified route. This error is typically not caused by issues with the input or request but is instead attributed to challenges related to toll rate databases, mapping discrepancies, or computational difficulties in determining the correct toll charges for the given route.
{
"status": 500,
"code": "TOLLING_ERROR",
"value": "Error calculating tolls"
}SERVICE_ERROR
The server encountered an unexpected issue while processing your request. This error indicates a problem on the server side and is unrelated to your input or request.
Internal Server Errors usually occur because of technical issues, such as server misconfigurations, resource limitations, or software bugs.
{
"status": "SERVER_ERROR",
"message": "Internal Server Error"
}504 GATEWAY_TIMEOUT
The “504 Gateway Timeout” error in the context of Kubernetes, specifically on Amazon Elastic Kubernetes Service (EKS), typically occurs when the pods responsible for processing incoming requests are unable to respond within the expected time frame. This error is an indication that the request from the client could not be fulfilled due to a timeout in communication between the client, the Kubernetes service, and the underlying containers or pods.
To understand the root cause and theory behind this error, we need to consider various factors that contribute to its occurrence:
- Pod Crashes and Failures: One possible reason for the “504 Gateway Timeout” error is when the pods that are meant to handle incoming requests crash or experience unexpected failures. This can be due to various issues such as resource constraints, misconfigurations, or bugs in the application code running inside the containers.
- Unhandled Internal Server Errors: Inside the containers or pods, applications may encounter unhandled internal server errors. These errors could be caused by exceptions, uncaught exceptions, or bugs in the code. When such errors occur, they can lead to the application unexpectedly crashing or failing to respond to requests.
Warnings for API Requests and Responses
Warnings are messages that indicate potential issues or considerations related to the data or request sent to the SDK.
For a thorough comprehension of these warnings please refer to this article: Don’t get trolled by tolls: Avoid common polyline endpoint pitfalls.
locTimes_error
{
"type": "locTimes_error",
"message": "LocTimes may not be accurate given that some sections have really high speeds. We suggest you check locTimes"
}- Resolution: Examine the input locTimes. For the input locTimes to be correct, the vehicle needs to travel at really high speeds. For accurate results, validate and fix the locTimes.
points_straight_line
{
"type": "points_straight_line",
"message": "Based on the input route, distance between two points is large at index: <list of index> with distance: <distance> km"
}- Resolution: Examine the input route data and make adjustments to minimize substantial gaps between the recorded data points. By doing so, you can enhance the accuracy and reliability of the results generated during the routing process. Reducing these gaps ensures that the route’s representation closely aligns with the actual path taken, resulting in more precise and reliable outcomes.
duplicate_locTimes
{
"type": "duplicate_locTimes",
"message": "We've excluded duplicate entries in locTimes. We recommend sending locTimes without repeats"
}- Resolution: Before sending the request, make sure there are no duplicate entries in the “locTimes”. This step is essential as duplicate timestamps can cause inaccuracies in route mapping and create confusion in determining the correct chronological order of recorded locations.
missing_id_from_pair
{
"type": "missing_id_from_pair",
"message": "ID X belongs to a closed system, and toll calculation demands an entry/exit ID pair. The provided route indicates only one ID. Please ensure the complete route is provided."
}- Resolution: Ensure that the route data contains both entry and exit IDs to calculate tolls correctly for closed systems. We need to know the complete route with entry and exit information. Please refer to this article for more information: Understanding Toll Calculation for Closed Systems: Entry and Exit ID Pairing
missing_old_toll_data
{
"type": "missing_old_toll_data",
"message": "The queried date is earlier than our available toll data for this location. An error occurred for Start ID: X, End ID: Y, and Timestamp: Z. If you need older data, email api@tollguru with this response"
}- Resolution: If you require toll data for earlier dates, please contact api@tollguru.com with the response for further help.
Customer faced commonly seen errors
Regional Defaults Update Challenges
- Updates related to vehicle type changes in certain regions have led to issues.
- Example Issue: Renaming vehicle types, such as a change from “5AxlesTruck” to “5axlestruck”, led to issues with fuel calculations, producing unexpected results due to fuel efficiency parameters related to vehicles
- Current Approach: To check for such inconsistencies, we’ve implemented validation checks. These checks maintain vehicle-type data integrity in various tables and ensure consistent results for our users.
AWS Fargate’s Resource Constraints
- TollGuru(R) is hosted on AWS Fargate, which has resource quotas. When the quota was exceeded, it affected our service’s responsiveness.
- Noted Issue: During instances of high demand, the exhaustion of quotas can cause some of our service pods to be in a “pending” state, causing delays.
- Recommended Action: To maintain optimal performance, it’s crucial to monitor resource usage and, when necessary, adjust the resource allocations. This proactive measure ensures uninterrupted service to our users.
Conclusion
This runbook serves as a comprehensive guide to address the most frequent issues while interacting with the TollGuru SDK. By following the resolutions provided for each error, developers and support teams can ensure a smooth operation of the SDK and enhance the user experience.
