Documentation
Overview Quick Start Authentication API Endpoints Code Examples Error Codes Rate Limits Changelog
Swagger UI ReDoc

Error Codes Reference

Understanding and handling API errors properly ensures a robust integration. All errors follow a consistent format with helpful messages.

Error Response Format

All error responses include a JSON object with error details:

{
  "error": "Error type",
  "detail": "Detailed error message",
  "field": "field_name"  // Optional: for validation errors
}
400 Bad Request

The request was invalid or cannot be served.

Common Causes:
  • Invalid VIN format
  • Missing required parameters
  • Invalid JSON in request body
Example Response:
{'error': 'Invalid VIN format', 'detail': 'VIN must be exactly 17 characters'}
How to Fix:
  • Ensure VIN is exactly 17 characters
  • Verify VIN contains only valid characters (A-Z, 0-9, excluding I, O, Q)
  • Check that all required parameters are included
  • Validate JSON syntax in request body
401 Unauthorized

Authentication credentials were missing or invalid.

Common Causes:
  • Missing API key or token
  • Invalid API key or token
  • Expired authentication token
Example Response:
{'detail': 'Authentication credentials were not provided.'}
How to Fix:
  • Include the Authorization: Token or X-API-Key header
  • Verify your credentials are correct
  • Check that your token/key hasn't been revoked
  • Ensure proper header formatting
403 Forbidden

The request is valid but you do not have access to the resource.

Common Causes:
  • Inactive API key
  • Insufficient permissions
  • Account suspended
Example Response:
{'detail': 'This API key has been deactivated.'}
How to Fix:
  • Verify API key is active in your account settings
  • Check account status and subscription
  • Ensure you have permission for the requested resource
  • Contact support if account is suspended
429 Too Many Requests

Rate limit exceeded or subscription quota reached.

Common Causes:
  • Exceeded rate limit (requests per minute)
  • Exceeded monthly subscription quota
  • Too many concurrent requests
Example Response:
{'error': 'Subscription limit exceeded', 'detail': 'You have exceeded your monthly decode limit of 1000', 'usage': {'used': 1000, 'limit': 1000, 'resets_at': '2024-02-01T00:00:00Z'}}
How to Fix:
  • Check the Retry-After header for wait time
  • Implement exponential backoff in your requests
  • Monitor your usage with the /user/usage endpoint
  • Consider upgrading your subscription for higher limits
  • Spread requests over time to avoid bursts
500 Internal Server Error

An error occurred on the server.

Common Causes:
  • Server configuration issue
  • Database connection error
  • Unexpected server error
Example Response:
{'error': 'Internal server error', 'detail': 'An unexpected error occurred. Please try again later.'}
How to Fix:
  • This is a server error - retry the request
  • If persistent, contact support with request details
  • Check our status page for incidents
503 Service Unavailable

The service is temporarily unavailable.

Common Causes:
  • Service maintenance
  • Third-party API unavailable
  • Server overload
Example Response:
{'error': 'Service temporarily unavailable', 'detail': 'NHTSA API is currently unavailable. Please try again later.'}
How to Fix:
  • Service is temporarily unavailable - retry later
  • Check the Retry-After header if present
  • Monitor our status page
  • Implement retry logic with exponential backoff

Best Practices for Error Handling

1. Implement Retry Logic

For 5xx errors and rate limits, implement exponential backoff:

// Exponential backoff example
let retries = 0;
const maxRetries = 3;
const baseDelay = 1000; // 1 second

async function requestWithRetry(url, options) {
    while (retries < maxRetries) {
        try {
            const response = await fetch(url, options);
            if (response.ok) return response;

            if (response.status >= 500 || response.status === 429) {
                const delay = baseDelay * Math.pow(2, retries);
                await new Promise(resolve => setTimeout(resolve, delay));
                retries++;
                continue;
            }

            // Don't retry client errors
            throw new Error(`HTTP ${response.status}`);
        } catch (error) {
            if (retries >= maxRetries - 1) throw error;
            retries++;
        }
    }
}
2. Log Errors Appropriately

Capture important error details for debugging:

  • Request ID (from response headers)
  • Timestamp
  • Error code and message
  • Request parameters (excluding sensitive data)
3. Handle Rate Limits Gracefully

Respect rate limits to maintain service availability:

  • Check usage before batch operations
  • Implement client-side rate limiting
  • Use caching to reduce API calls
  • Queue requests during rate limit periods
4. Provide User-Friendly Messages

Translate API errors into helpful user messages:

const userMessages = {
    400: "Please check the VIN and try again",
    401: "Please log in to continue",
    429: "Too many requests. Please wait a moment",
    500: "Something went wrong. Please try again",
    503: "Service temporarily unavailable"
};

Need Help?

If you're experiencing persistent errors: