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.

Response Times

ARC runs its own VIN decode and battery enrichment infrastructure. Active lookups usually return in a few hundred milliseconds—Explorer by VIN typically averages around 400ms (250–550ms). The first request after a quiet period may take up to about 10 seconds while the pipeline warms up; that is expected, not an outage.

Scenario	Typical	Notes
Single VIN decode (active)	Under 1 second	Typical responses land in a few hundred milliseconds when the decode service is already running.
Explorer by VIN (active)	250–550ms (~400ms avg)	Vehicle decode plus battery enrichment. Recent production traffic clusters around 300–500ms per lookup once warm.
First request after idle	Up to ~10 seconds	The initial lookup after inactivity may take longer while ARC initializes its decode pipeline. Later requests in the same window are much faster.
Batch decode (active)	Under 1 second per batch	Batch throughput improves once warmed up. The first batch in a burst may be slower than the ones that follow.

Show a loading state in interactive UIs—most users will only notice the warm-up on the first lookup.
For overnight or scheduled jobs, send a single warm-up request before processing a queue to avoid surprising latency on the first real record.
Use batch decode for backfills and imports; per-VIN latency drops sharply once the pipeline is active.

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.