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.

Idempotent Requests

Include an Idempotency-Key header on every API request. Create a unique key for each logical request, then reuse that key only when retrying the exact same request.

Keys may contain 1–200 visible characters. UUIDs or another collision-resistant identifier are recommended.
Send a retry exactly as originally submitted, using the same endpoint and the exact same query string or request body. Preserve parameter order, VIN order, and JSON formatting. After a request has passed validation and been accepted for processing, reusing its key with a different request returns 409 Conflict.
A repeated batch request returns the original batch response, including its results and per-VIN errors. It does not run failed VINs again.
Use a new key when the request changes or when you intentionally want a fresh decode.
Single-result endpoints use the key to prevent duplicate usage accounting while processing the retry normally.

Idempotent Request

curl "https://api.autoresourceco.com/api/v1/vin/decode?vin=5YJ3E1EA8KF000001" \
  -H "X-API-Key: your_api_key_here" \
  -H "Idempotency-Key: 9d34c35b-8b12-4c0a-8a61-d14f651c9440"

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.
GET /api/v1/explorer/vehicle/by-battery-external-id	60 requests per minute	Per API key. A successful lookup consumes one Explorer unit; a missing battery returns 404 without consuming monthly usage, but the request still counts toward the per-minute rate limit.
GET /api/v1/explorer/vehicle/by-battery-name	60 requests per minute	Per API key. Exact-name misses return 404 without consuming monthly usage; the request still counts toward the per-minute rate limit.
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",
    "code": "1004",
    "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.
400	Idempotency key required	The Idempotency-Key header is missing, empty, or contains only whitespace.
400	Invalid idempotency key	Idempotency-Key is longer than 200 characters or contains invalid header text.
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	ARC does not have a vehicle record for the requested VIN.
404	Not found	The requested battery external ID or exact battery name has no active match. These misses do not consume monthly usage.
409	Idempotency conflict	An Idempotency-Key is reused with a different endpoint, query string, or request body.
422	Validation error	Typed input is invalid, such as an out-of-range year or a malformed non-VIN query parameter.
422	VIN resolve failed	Explorer by-VIN only: the VIN decoded, but the result has no valid model year, make, or model to resolve battery fitment (code 1096). Retrying the same VIN returns the same result.
429	Rate limit exceeded / Limit reached	The request bucket is exhausted or a monthly API entitlement limit has been reached.
500	Decode failed	ARC cannot complete the decode request.
502	Decode failed	The ARC decoding service is temporarily unavailable or returns a response that cannot be processed.
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 .