Troubleshooting Common API Errors

Overview

When integrating with TrackVia APIs, errors generally fall into a few common categories:

• Authentication and authorization  
• Validation failures
• Timeout and performance issues
• Rate limiting
• Data integrity conflicts
• Connectivity problems

General API Troubleshooting Checklist

When troubleshooting API failures:

1. Verify authentication
2. Confirm endpoint URLs
3. Validate payload structures
4. Review middleware logs
5. Check HTTP status codes
6. Inspect App Script behavior
7. Review recent configuration changes
8. Confirm environment-specific credentials
9. Test with simplified payloads
10. Check for platform incidents or outages

COMMON ERROR CODES

❗401 Unauthorized

What It Means

The API request could not be authenticated.

Common Causes

• Expired Access Token
• Incorrect Access Token
• Invalid UserKey
• Revoked credentials
• Inactive API user
• Incorrect environment credentials

Example Error

HTTP GET failed: unauthorized (401)

🛠️Resolution Steps

1. Verify the Access Token is still active
2. Confirm the API user is active and enabled
3. Validate the UserKey
4. Ensure sandbox and production credentials are not mixed
5. Regenerate the token if necessary
6. Update middleware or integration configurations

🥇Best Practices

• Use dedicated integration/service accounts
• Rotate tokens on a schedule
• Monitor for expiring credentials

❗403 Forbidden

What It Means

Authentication succeeded, but the user does not have permission to perform the requested action.

Common Causes

• Missing table permissions
• Insufficient role access
• Restricted API operations
• Environment access limitations

Resolution Steps

1. Review the API user's permissions
2. Verify role assignments
3. Confirm access to the target table or application
4. Validate Role permissions

❗404 Not Found

What It Means

The requested resource does not exist.

Common Causes

• Incorrect endpoint URL
• Invalid table ID
• Invalid application ID
• Deleted resource
• Typographical errors

🛠️Resolution Steps

1. Verify endpoint URLs
2. Confirm application and table IDs
3. Validate API routing configuration
4. Ensure the target object still exists
5. Confirm the provided id is correct. 
   👀NOTE: use the id and not a “Record Id”

❗429 Too Many Requests

What It Means

The integration exceeded API rate limits.

Common Causes

• Excessive polling
• Large bursts of requests
• Inefficient synchronization logic
• Recursive integration loops

🛠️Resolution Steps

1. Reduce request frequency
2. Batch requests where possible
3. Add retry backoff logic
4. Avoid unnecessary polling
5. Cache frequently requested data

🥇Best Practices

• Use event-driven integrations when possible
• Avoid continuous polling loops
• Monitor integration throughput

❗500 Internal Server Error

What It Means

The server encountered an unexpected condition while processing the request.

Common Causes

• App Script runtime exceptions
• Invalid payload structures
• Unexpected null values
• Backend processing failures
• Temporary platform instability

🛠️Resolution Steps

1. Review App Script configuration
2. Validate payload data
3. Check for null or invalid field values
4. Retry the request if appropriate
5. Contact support if the issue persists

.