Skip to main content

Troubleshooting Common API Errors

  • Updated

Overview

This article covers the most frequently encountered HTTP status errors when integrating with the TrackVia API. Where you see the error depends on which system is making the API call. If Workato is calling TrackVia, errors are typically visible in Job History, under Failed Jobs or Step output details.

The errors covered in this article are:

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 429 Too Many Requests
  • 500 Internal Server Error

For non-HTTP errors or issues not covered here, see the Related Articles section at the bottom of this page, or contact TrackVia Support with the error message, endpoint called, timestamp, and integration tool you are using.

Jump to Section

General API Troubleshooting Checklist

Before diving into a specific error code, work through this checklist. Most API failures can be narrowed down quickly by confirming these basics:

  • Verify authentication — confirm your Access Token and UserKey are valid and have not expired.
  • Confirm endpoint URLs — check for typos, missing path segments, or incorrect application/table IDs.
  • Validate payload structures — ensure required fields are present and data types are correct.
  • Review middleware logs — check your integration platform (e.g., Workato Job History) for detailed error output.
  • Check HTTP status codes — use the specific error code sections below to identify the root cause.
  • Inspect App Script behavior — if using App Scripts, review script logic for runtime exceptions or unexpected null values.
  • Review recent configuration changes — a recent role, permission, or credential change may be the cause.
  • Confirm environment-specific credentials — sandbox and production environments use separate credentials; do not mix them.
  • Test with simplified payloads — strip the request down to the minimum required fields to isolate the issue.
  • Check for platform incidents or outages — verify TrackVia is operational before spending time debugging your integration.

401 Unauthorized

What It Means

The API request could not be authenticated. The server did not recognize or could not validate the credentials provided.

Common Causes

  • Expired Access Token
  • Incorrect Access Token
  • Invalid UserKey
  • Revoked credentials
  • Inactive API user
  • Incorrect environment credentials (e.g., using sandbox credentials against production)

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 with the new credentials

Best Practices

  • Use dedicated integration or service accounts rather than personal user credentials
  • Rotate tokens on a regular schedule
  • Monitor for expiring credentials and set up alerts where possible

403 Forbidden

What It Means

Authentication succeeded, but the authenticated user does not have permission to perform the requested action. A 403 is an authorization failure, not an authentication failure — the server recognized who you are, but is refusing the request based on your permissions.

Common Causes

  • Missing table permissions on the API user's role
  • Insufficient role access for the requested operation
  • Restricted API operations (e.g., attempting to delete when only read access is granted)
  • Environment access limitations

Example Error

HTTP GET failed: forbidden (403)

Resolution Steps

  1. Review the API user's role and permissions in TrackVia
  2. Verify the role includes access to the target table or application
  3. Confirm the role permits the specific operation being attempted (read, write, delete)
  4. Validate that role permissions have been saved and are active

Best Practices

  • Use a dedicated service account for API integrations with a role scoped to only what is needed
  • Avoid using admin or super-admin accounts for automated integrations
  • Document the permissions required for each integration so they can be reproduced if the account is recreated

404 Not Found

What It Means

The requested resource does not exist. The server understood the request but could not find the target endpoint, table, application, or record.

Common Causes

  • Incorrect endpoint URL
  • Invalid table ID or application ID
  • Deleted or renamed resource
  • Typographical errors in the URL or ID

Example Error

HTTP GET failed: not found (404)

Resolution Steps

  1. Verify the endpoint URL is correct and complete
  2. Confirm the application and table IDs match the target environment
  3. Validate API routing configuration in your integration tool
  4. Ensure the target object still exists and has not been deleted
  5. Confirm you are using the correct ID field (see note below)

⚠ Note: Record ID vs. Internal ID
When referencing TrackVia records via the API, always use the internal primary key (the ID field), not the visible Record ID field. These are two different values. Using the Record ID field in API calls will result in a 404 or incorrect results.

Best Practices

  • Store application and table IDs in a central configuration rather than hardcoding them throughout your integration
  • Re-validate IDs when migrating between sandbox and production environments

429 Too Many Requests

What It Means

The integration exceeded the TrackVia API rate limits. Rate limiting prevents any single integration or application from overwhelming the API. When the limit is exceeded, TrackVia returns a 429 response and additional requests are rejected until the rate window resets.

TrackVia API Rate Limits

Limit Type Limit
Per minute 1,200 API calls per minute
Per month 11,000,000 API calls per month

Common Causes

  • Excessive polling loops querying the API on a tight schedule
  • Large bursts of requests triggered simultaneously
  • Inefficient synchronization logic making redundant calls
  • Recursive integration loops that trigger additional API calls

Resolution Steps

  1. Reduce request frequency in your integration
  2. Batch requests where the API supports it
  3. Implement retry logic with exponential backoff
  4. Eliminate unnecessary polling
  5. Cache frequently requested data to reduce repeat calls

Best Practices

  • Use event-driven integrations instead of polling loops wherever possible
  • Monitor integration throughput to catch rate limit approaches before they cause failures
  • Design integrations to handle 429 responses gracefully with automatic retry

500 Internal Server Error

What It Means

The server encountered an unexpected condition while processing the request. This error originates on the TrackVia side and may indicate a problem with the request payload, an App Script exception, or temporary platform instability.

Common Causes

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

Example Error

HTTP POST failed: internal server error (500)

Resolution Steps

  1. Review App Script configuration for runtime errors or exceptions
  2. Validate the payload — ensure all required fields are present and correctly formatted
  3. Check for null or empty field values that may be causing processing failures
  4. Retry the request — if the error is due to temporary instability, a retry may succeed
  5. Check for active platform incidents before further investigation
  6. Contact TrackVia Support if the issue persists, providing the full error message, endpoint, and timestamp

Best Practices

  • Validate all payloads against expected field types and requirements before sending
  • Include null checks in App Scripts to prevent unexpected exceptions
  • Log full request and response details in your integration tool to aid troubleshooting

Still Stuck?

If you have worked through the relevant error section above and the issue persists, contact TrackVia Support. To help us resolve your issue as quickly as possible, please include the following in your support request:

  • The full error message
  • The API endpoint being called
  • The HTTP method used (GET, POST, PUT, DELETE)
  • The timestamp of the failure
  • The integration tool or platform involved (e.g., Workato, custom script)
  • Any recent configuration changes that may be relevant

Related Articles

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk