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

Error Response Format


HTTP Status Codes

400 Bad Request

Cause: Invalid request parameters or malformed JSON. Example:
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:
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:
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:
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:
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:
Response Headers:
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:
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


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