Tire API Error Handling & Wheel Fitment Troubleshooting Guide
Master common API errors, wheel fitment validation, and rate limiting strategies
HTTP Status Codes Overview
The Tire API uses standard HTTP status codes to indicate request success or failure. Understanding these codes is essential for proper wheel and tire fitment validation:
- 200 OK
Request successful, wheel/tire data returned - 201 Created
Resource successfully created - 400 Bad Request
Invalid tire size or wheel parameters - 401 Unauthorized
Missing or invalid API key - 403 Forbidden
Valid key but insufficient permissions - 404 Not Found
Vehicle or tire size not in wheel database - 429 Too Many Requests
Rate limit exceeded - 500 Internal Server Error
Server error (temporary) - 503 Service Unavailable
API temporarily down
Error 1: 401 Unauthorized - Authentication Failed
What It Means: Your API request is missing a valid API key or the key is invalid/expired.
Common Causes
- API key not included in request headers
- Incorrect header name (should be x-api-key)
- API key is expired or revoked
- Extra whitespace in API key
Interactive Code Example
✓ CORRECT:
curl -H "x-api-key: YOUR_API_KEY" \
"https://tire.vdim.app/api/v1/search_allyear"
JavaScript Error Handling:
const apiKey = process.env.TIRE_API_KEY;
if (!apiKey) throw new Error('API key missing');
const response = await fetch(
'https://tire.vdim.app/api/v1/search_allyear',
{ headers: { 'x-api-key': apiKey.trim() } }
);
✓ Verification Checklist:
- Log into your tire.vdim.app dashboard
- Navigate to API Keys section
- Copy the full key (no spaces)
- Verify it's an active key
Error 2: 400 Bad Request - Invalid Tire/Wheel Parameters
What It Means: Your request has invalid tire size, wheel dimensions, or other malformed data.
Tire Size Format Validation
Format: WIDTH/ASPECT_RATIORDDIAMETER
✓ Valid Tire & Wheel Sizes:
225/60R17 → Std sedan wheel fitment
275/45R19 → Performance wheel size
215/70R16 → Truck wheel specification
❌ Invalid Formats:
225-60-17 → Wrong wheel size format
225x60x17 → Incorrect separators
💡 Use tire.vdim.app API documentation for exact wheel and tire size validation requirements.
Error 3: 429 Too Many Requests - Rate Limited
What It Means: You've exceeded your API quota for the current time period.
Rate Limits by Plan
- Free Plan: 300 requests/day
- Growth Plan: 5,000 requests/day
- Enterprise Plan: 50,000+ requests/day
Interactive Retry Logic
async function retryWithBackoff(url, maxRetries=3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
const response = await fetch(url);
if (response.status === 429) {
const wait = Math.pow(2, attempt - 1) * 1000;
await new Promise(r => setTimeout(r, wait));
continue;
}
return await response.json();
}
}
✓ Solutions:
- Implement exponential backoff retry
- Cache tire/wheel data locally
- Monitor usage at tire.vdim.app/api/docs
Error 4: 404 Not Found - Wheel/Tire Not in Database
What It Means: The vehicle, tire size, or wheel specification doesn't exist in the database.
Troubleshooting Steps:
- Verify make/model at tire.vdim.app/search_allmake
- Check tire format matches API specs
- Ensure vehicle wheel is in database
Best Practices for Error Handling
1. Validate Tire & Wheel Data First
Validate tire size and wheel parameters locally before making API calls to reduce failed requests.
2. Implement Timeout Handling
Set timeout of 5-10 seconds for all requests to prevent hanging connections.
3. Monitor Rate Limit Headers
Check X-RateLimit headers on every response to track wheel/tire API quota.
Debugging Wheel & Tire Fitment Checklist
- ✓ Is your API key valid and in the x-api-key header?
- ✓ Are you below your rate limit? (check /usage)
- ✓ Is API healthy? (check tire.vdim.app/api/health)
- ✓ Is tire size in correct format (e.g., 225/60R17)?
- ✓ Are wheel/vehicle parameters valid?
- ✓ Are you handling 429 responses with backoff?
- ✓ Is your network connection stable?
Ready to Integrate Tire API?
Start building wheel fitment solutions with tire.vdim.app today.
Get Started
Pro Tip: Most wheel and tire API errors are preventable with proper validation. Implement error handling early to ensure accurate vehicle wheel fitment and better user experience.