Quickstart
One header, one call, structured JSON back.
1. Get a key
Sign up (free, 20 decodes a month) and copy the API key from your dashboard.
2. Decode
curl -X POST https://api.vinvalid.org/api/vin \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"vin": "WVWZZZ1KZE0000000"}'The VIN is normalized before validation: all whitespace (edges and internal) is stripped and the rest upper-cased, so"wvw zz z1kz e000 0000" and WVWZZZ1KZE0000000 are the same call. I, O and Q are still rejected — they are not part of the VIN alphabet.
3. Read the answer
Every field is { value, source } — source: "registry" is the observed value, source: "derived" is computed from the VIN itself.alternatives carries the near-misses.
Errors
| Status | Code | What it means |
|---|---|---|
| 400 | INVALID_VIN | The VIN failed validation (11–17 chars, no I/O/Q). Case and whitespace (anywhere) are normalized automatically — lowercase and space-blocked pastes are fine. Fix the string and retry. |
| 401 | INVALID_API_KEY | No key, or a key that is unknown/revoked. Use a fresh key from your dashboard. |
| 401 | SUBSCRIPTION_INACTIVE | Your key is attached to a paused or past-due subscription. Fix billing, it resumes automatically. |
| 429 | RATE_LIMITED | You went over the per-minute burst for your tier. Wait for Retry-After — and note: tripping the burst blocks your key for 1 hour. |
| 429 | QUOTA_EXCEEDED | Your monthly quota is spent (or the overage cap is hit). Response carries resetsAt — or raise your plan. |
| 402 | PAST_DUE | Stripe marked you past due. Pay the invoice in your billing portal; your key works again once settled. |
Limits, in plain English
Every plan has two numbers: a monthly quota (how many decodes you can make in a month) and a per-minute burst (how fast you can go). The per-plan table with prices lives on the landing page; here is only what the numbers mean.
Overage: on paid tiers you can go past your monthly quota at the tier's per-lookup rate — but only up to 100% extra (double your quota), unless you turn it off in your dashboard. Free tier: no overage.
The 1-hour penalty: if you send more than your per-minute limit in one minute, your key is blocked for a flat 1 hour. It is not a billing penalty — the clock simply runs, and your key works again after. Watch the countdown in your dashboard.