Errors and Limits

Public endpoints use standard HTTP status codes, structured error payloads in the detail field, and explicit rate-limit headers for successful and throttled responses.

Build retries deliberately

429 responses include both Retry-After headers and retry_after in the error payload. Honor those values instead of retrying immediately.

Rate Limits

Endpoint	Limit	Notes
GET /api/v1/vin/decode	60 requests per minute	Per API key. Success and 429 responses include X-RateLimit-* headers.
GET /api/v1/explorer/vehicle/by-vin	60 requests per minute	Per API key. Explorer responses use the same X-RateLimit-* header contract.
GET /api/v1/explorer/vehicle/by-ymm	60 requests per minute	Per API key. Monthly plan exhaustion can also surface as a 429 with reason_code API_LIMIT_REACHED.
POST /api/v1/vin/decode-batch	10 requests per minute	Per API key. Intended for bulk jobs; each successful VIN decode is billed individually.

Rate-Limit Headers

Header	Type	Description
X-RateLimit-Limit	integer	Maximum requests allowed in the current bucket.
X-RateLimit-Remaining	integer	Requests remaining before the current bucket is exhausted.
X-RateLimit-Reset	unix timestamp	UTC timestamp for when the current bucket resets.
Retry-After	integer	Returned on 429 responses to indicate how many seconds to wait before retrying.

Error Response Example

{
  "detail": {
    "error": "Invalid VIN",
    "message": "VIN check digit (position 9) is invalid"
  }
}

429 Response Example

{
  "detail": {
    "error": "Rate limit exceeded",
    "message": "Too many requests. Limit: 60 requests per minute. Try again in 41 seconds.",
    "retry_after": 41
  }
}

Common Errors

HTTP	Error	When It Happens
400	Invalid VIN	A single VIN fails format or check-digit validation before decode begins.
400	Invalid batch request	The batch payload is empty, malformed, or exceeds the maximum batch size.
401	Missing API key / Invalid API key	The X-API-Key header is missing or the provided key cannot be validated.
402	Payment required	The account behind the API key does not currently have API access.
404	Decode failed	The upstream vehicle data source returns no vehicle record for the requested VIN.
422	Validation error	Typed input is invalid, such as an out-of-range year or missing required query parameter.
429	Rate limit exceeded / Limit reached	The request bucket is exhausted or a monthly API entitlement limit has been reached.
500	Decode failed	An unexpected internal error occurs during decode processing.
502	Decode failed	The upstream VIN provider timed out, failed, or returned an unusable payload.
503	Database unavailable	Explorer lookup data is temporarily unavailable. Retry the request shortly.

Batch Partial Failures

Batch decode can succeed overall while returning per-VIN failures in the errors array. Successful VINs are still returned in results.