Troubleshoot common Car List API issues

Most Car List API problems can be isolated by checking the HTTP status, JSON error message, token configuration, and the server making the request. This guide covers the most common integration issues and the details that are easy to overlook.

Start with the quick checks below. If the issue remains, jump to the section matching your status code or symptom.

Five-minute troubleshooting checklist

1. Confirm the request URL begins with `https://carlistapi.com/api/v1` when calling the API directly.

2. Confirm the request includes `Authorization: Bearer YOUR_API_TOKEN` and `Accept: application/json`.

3. Run the test from the same server or hosting environment used by your application.

4. Check that the server's public outbound IP is included on the token.

5. Sign in to the [user dashboard](https://carlistapi.com/user/dashboard) and confirm the account, subscription, product access, token, and usage allowance are active.

6. Record the HTTP status and JSON response body. Do not diagnose an API request from the message displayed by your frontend alone.

7. If you changed an SDK `.env` value, clear your application's cached configuration before testing again.

Isolate the request with cURL

Before debugging your framework, SDK, frontend, or application logic, make one simple request with cURL:

curl -i "https://carlistapi.com/api/v1/car-data/get-years/asc" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json"

Run this command from the same server that makes your production requests. A successful response returns HTTP 200 and a JSON array of supported years.

This test separates API access from application code:

• If cURL also fails, focus on the token, outbound IP, subscription, product access, usage, URL, or service response.

• If cURL succeeds, focus on your SDK configuration, environment variables, cached configuration, URL construction, response parsing, or application code.

Never paste the command into a ticket, chat, screenshot, or log with the real token still present. Replace it with REDACTED first.

Start with the HTTP status

Errors normally include a safe JSON error value. Validation performed before a controller may instead include Laravel-style message and errors fields. Always inspect the body as well as the status.

Fix 401 authentication errors

“API token is missing”

The request did not include a usable Bearer token.

Confirm the header is formatted exactly like this:

Authorization: Bearer YOUR_API_TOKEN

Common mistakes include:

• Sending the token in the query string instead of the header

• Using Authentication instead of Authorization

• Omitting the word Bearer

• Adding an extra colon, quote, line break, or space to the token

• Sending the request from browser code that removes or blocks the header

“Invalid API token” or an unauthenticated response

The supplied token cannot be used for the request. It may have been copied incorrectly, revoked, expired, or replaced.

Create or review tokens in the user dashboard. If there is any chance the token was exposed, revoke it and create a replacement rather than continuing to troubleshoot with the compromised value.

When using an SDK, store only the raw token in the environment variable. Do not include the Bearer prefix—the SDK adds the authorization scheme.

“IP address mismatch”

The public IP observed by Car List API is not on the token allowlist.

Check the public outbound or egress IP of the server making the request—not:

• Your laptop's IP when the application runs on a hosted server

• The website's inbound IP

• A private address such as 127.0.0.1, 10.x.x.x, or 192.168.x.x

• A load balancer's address when outbound traffic uses a different gateway

• A container's internal address

Some hosting platforms use more than one outbound IP. Add every address that can make production requests. If requests alternate between success and 403, a rotating or incomplete egress-IP allowlist is a likely cause.

Run the cURL isolation test from the production server after updating the token.

“Account disabled” or “API access disabled”

The account or its API access is not currently enabled. Review the account state in the dashboard. If you believe the restriction is incorrect, contact support with the account email and sanitized response—never the API token.

“An active eligible subscription is required”

The account does not currently resolve to an active eligible plan. Check for an expired, canceled, incomplete, past-due, or otherwise inactive subscription.

If you recently completed checkout, refresh the dashboard and confirm the active plan is displayed before creating another token or request.

“Your subscription does not include access to this API product”

The plan is active but does not include the requested automotive, powersports, or VIN Decoder product. Review the plan entitlements and use an included product or choose a suitable plan.

Fix 404 and incorrect-route problems

A 404 can mean either that the URL does not match an API route or that the requested vehicle record does not exist.

Check these items first:

• The domain is carlistapi.com.

• Direct API URLs include /api/v1.

• The endpoint path matches the API documentation.

• Dynamic values are URL-encoded.

• The request did not accidentally duplicate /api or /v1.

• The HTTP method is correct.

For example, the direct years endpoint is:

https://carlistapi.com/api/v1/car-data/get-years/asc

The VIN Decoder is a POST, not a GET:

POST https://carlistapi.com/api/v1/vin-decoder/decode

If the response says Vehicle data not found, the route worked but the requested record was not found. Confirm that the UUID came from the current dependent lookup flow and was not manually constructed, truncated, or copied from a different environment.

Direct API and SDK base URLs are different

This is a common configuration mistake.

When constructing direct API requests, use:

https://carlistapi.com/api/v1

When configuring either official PHP SDK, use:

CAR_LIST_API_URL=https://carlistapi.com/api
CAR_LIST_API_VERSION=v1

Do not add /v1 to the SDK base URL. The SDK appends the configured version. Setting the base URL to https://carlistapi.com/api/v1 can produce a duplicated path such as /api/v1/v1/....

After changing Laravel environment values, clear cached configuration:

php artisan optimize:clear

Also confirm the running PHP process receives the same environment values as your terminal. A command that succeeds in a shell does not prove PHP-FPM, a queue worker, or a container has the same configuration.

Fix 422 validation errors

A 422 means the server understood the request but rejected one or more values.

Common causes include:

• A year outside the supported format or range

• An overlong make, model, trim, engine, fuel type, drive type, body style, or powersports type

• A model used with the wrong year or make

• A trim used with the wrong year, make, or model

• A malformed VIN or invalid model year

• A validly formatted VIN that the provider could not decode

Use values returned by the preceding endpoint instead of accepting or constructing arbitrary combinations.

Automotive lookups should follow:

Year → Make → Model → Trim → Engine → Vehicle UUID → Details

Powersports lookups should follow:

Type → Year → Make → Model → Submodel → Vehicle UUID → Details

When an earlier selection changes, clear every dependent selection below it. For example, changing the year should clear the selected make, model, trim, engine, and UUID.

URL-encode every dynamic path value

Makes, models, trims, engines, body styles, fuel types, drive types, and powersports types can contain spaces, punctuation, slashes, or other reserved URL characters.

Encode each dynamic path segment using the appropriate function for your language. In PHP, use rawurlencode():

$make = rawurlencode('Mercedes-Benz');
$model = rawurlencode('C-Class');

Do not encode the entire URL at once. Encode each dynamic value before inserting it into the documented route.

Powersports types deserve particular attention because a displayed type may contain a slash. Passing an unencoded slash changes the path structure and can result in a 404, a validation error, or the wrong route match.

Fix 429 usage-limit responses

Automotive and powersports requests share the data API allowance. VIN Decoder requests use a separate VIN allowance.

A 429 response includes:

• limit

• used

• remaining

• reset_at

Do not immediately retry a 429. Repeating the request before the returned reset time will not solve the limit and can create unnecessary traffic.

Check both usage meters in the user dashboard. Exhausting the data API allowance does not automatically exhaust VIN Decoder usage, and exhausting VIN usage does not automatically block ordinary vehicle-data requests.

To reduce avoidable usage:

• Cache stable discovery responses such as years and makes

• Do not request data on every keystroke

• Debounce typeahead or search interfaces

• Prevent duplicate frontend submissions

• Avoid repeatedly loading the same options during one page view

• Reuse a resolved vehicle UUID when appropriate

Only successful data API requests consume the data allowance. Successful VIN decodes count even when the result is served from cache; failed VIN decodes do not consume the VIN allowance.

Fix unexpected empty or missing vehicle data

An empty array is not the same as an API error. It can mean that no records match the exact combination supplied.

If a lookup unexpectedly returns no options:

1. Confirm the previous endpoint actually returned the selected value.

2. Preserve its spelling, punctuation, and spacing.

3. Confirm the year, make, model, trim, engine, or type belongs to the same selection chain.

4. URL-encode the value when building the next route.

5. Clear application and client caches if they contain an older option list.

6. Reproduce the same request with cURL.

Do not hard-code vehicle lists or assume that a model is available in every year. Vehicle coverage changes over time, and dependent combinations matter.

VIN Decoder responses can also contain null fields when the source cannot resolve every specification. Preserve available values and show an intentional fallback for optional fields. Do not treat a partial VIN result as a complete failure, and do not fabricate missing data.

Check the response shape

Successful direct lookup endpoints return their array or object directly at the JSON root. There is no HTTP data envelope.

For example, a direct years response looks like:

[
    { "year": "2026" },
    { "year": "2025" }
]

If your application reads response.data.data, it may report an empty value even though the API succeeded.

The PHP SDKs are different: they return an SDK ApiResponse object whose decoded payload is available through its data property. Do not apply the raw HTTP parsing pattern to an SDK object or the SDK pattern to a raw HTTP response.

Browser and CORS errors

Production API tokens should not be exposed in browser JavaScript. If a browser reports a CORS error, move the Car List API request to your backend:

Browser → Your protected backend → Car List API

Your backend stores the token, validates browser input, applies your application's authorization and rate limiting, calls Car List API, and returns only the required data.

Do not work around a browser error by making a production token public or disabling your own security controls.

Timeouts, DNS, and connection failures

If no HTTP status or JSON body is returned, the request may not have reached the API.

Check:

• DNS resolution for carlistapi.com

• Outbound HTTPS access on port 443

• Server firewall or hosting egress restrictions

• TLS certificate validation and an up-to-date CA certificate bundle

• Proxy settings

• PHP cURL or your language's HTTP client configuration

• Connection and overall request timeouts

The official PHP clients default to a 5-second connection timeout, a 15-second overall timeout, and two retries. Customize these only when your environment requires it.

Retry only failures that are likely temporary. Use limited exponential backoff for connection failures, 502, or 503. Do not automatically retry 401, 403, 404, 405, or 422 without changing the request. Honor reset_at for 429 and Retry-After for 503.

Queue workers and cached configuration

Long-running workers do not automatically pick up every environment or code change.

If web requests work but queued requests fail:

• Confirm the worker runs the same release and PHP version as the web application

• Confirm the worker receives the same API URL, version, and token configuration

• Clear cached configuration after changing environment variables

• Restart the worker using your hosting platform's normal deployment process

• Confirm the worker's outbound IP is also allowed when it differs from the web server

Never restart production services with an improvised command if your platform already manages workers and deployments.

Before contacting support

If the issue remains, collect the following information. Complete diagnostic context usually avoids an extra round of questions:

• Approximate request time and timezone

• HTTP method and endpoint path

• HTTP status

• Sanitized JSON response body

• Whether the request used cURL, direct HTTP, the Laravel SDK, or the PHP SDK

• SDK and application versions when applicable

• Hosting environment and public outbound IP used for the request

• Token name or safe identifier from the dashboard—not the token value

• The dependent lookup steps that produced the failing value

• Whether the same request succeeds from another environment

• A minimal reproducible example with credentials removed

For vehicle-data questions, include the relevant year, make, model, trim, engine, type, or UUID. For VIN questions, mask the VIN unless support specifically requests it through an appropriate channel.

Never send:

• A complete API token

• Account password

• Stripe or payment credentials

• Unredacted environment files

• Screenshots containing secrets

• Full production logs without reviewing them for sensitive data

Next steps

- Review the complete API documentation

- Follow Get started with Car List API

- Read Decode a VIN with Car List API

- Check tokens, product access, and usage in the user dashboard

- Contact the Car List API team with the sanitized diagnostic details above if the issue remains