Skip to main content
All Trackyard API errors return a JSON object with an error field and a message field.

​
Error Response Format

{
  "error": "Brief error identifier",
  "message": "Human-readable error description"
}

​
HTTP Status Codes

​
400 Bad Request

Cause: Invalid request parameters or malformed JSON. Example: 
{
  "error": "hit_point_seconds requires duration_seconds",
  "code": "invalid_parameters"
}
How to fix:
  • Check parameter types and required fields
  • Validate JSON syntax
  • Review the API Reference for correct usage

​
401 Unauthorized

Cause: Missing, invalid, or expired API key. Example: 
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
How to fix:
  • Check that your API key is correct
  • Ensure you’re using the Authorization: Bearer header format
  • Verify the key hasn’t been revoked at app.trackyard.com/api-keys
  • Generate a new key if needed

​
402 Payment Required

Cause: Out of credits. Example: 
{
  "error": "Out of credits",
  "message": "Please top up or upgrade your plan"
}
How to fix:
  • Wait for monthly credit reset (1st of each month for free tier)
  • Upgrade your plan at app.trackyard.com/billing
  • Purchase additional credits (coming soon)

​
403 Forbidden

Cause: API key is valid but lacks permissions for the requested action. Example: 
{
  "error": "Forbidden",
  "message": "This feature requires a paid plan"
}
How to fix:
  • Check your account tier with GET /me
  • Upgrade your plan if needed
  • Verify you’re not accessing admin-only endpoints

​
404 Not Found

Cause: Requested resource doesn’t exist. Example: 
{
  "error": "Not Found",
  "message": "Track not found"
}
How to fix:
  • Verify the track ID is correct (from /search results)
  • Check for typos
  • The track may have been removed from the catalog

​
429 Too Many Requests

Cause: Rate limit exceeded. Example: 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}
Response Headers: 
Retry-After: 42
X-RateLimit-Remaining: 0
How to fix:
  • Wait retry_after seconds before retrying
  • Implement exponential backoff in your code
  • Upgrade to a higher tier for increased rate limits
  • See Rate Limits & Credits

​
500 Internal Server Error

Cause: Server-side error. Example: 
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
How to fix:
  • Retry the request after a short delay
  • If the problem persists, contact support@trackyard.com with the request_id

​
Handling Errors in Code

import requests
import time

def search_with_retry(query, api_key, max_retries=3):
    url = "https://api.trackyard.com/api/external/v1/search"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json={"query": query})
        
        # Success
        if response.status_code == 200:
            return response.json()
        
        # Rate limit - wait and retry
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        # Out of credits - stop immediately
        if response.status_code == 402:
            raise Exception("Out of credits. Please upgrade your plan.")
        
        # Other errors
        error = response.json()
        raise Exception(f"API error: {error.get('error')} (code: {error.get('code')})")
    
    raise Exception("Max retries exceeded")

​
Next Steps

Rate Limits & Credits

Learn how to avoid 402 and 429 errors

Authentication

Fix 401 errors with proper API key management

Code Examples

See error handling in full examples