Rate limits and reliable requests

Two features help your integration stay within limits and behave correctly under retries.

Rate limits

The live endpoint is throttled per API key. The default is 10 requests per minute per product, and some products may set a different limit. If you exceed the limit you'll receive an HTTP 429 Too Many Requests — back off and retry after a short pause.

If you're driving high volume, prefer bulk lookups (up to 50 registrations per request) over many single calls, and spread work evenly rather than bursting.

Idempotency keys (exactly-once billing)

Network timeouts happen. If you retry a request you don't want to be charged twice. Send an Idempotency-Key header with a unique value per logical operation:

curl "https://vehiclematic.com/products/vehicle-details/api/live/AB12CDE" \
  -H "X-VEHICLEMATIC-KEY: your_api_key" \
  -H "Idempotency-Key: order-4821-lookup-1"

If a retry arrives with the same key, the original result is returned and the credit is only ever deducted once. Use a stable, unique value tied to the work you're doing (an order id, a job id, etc.).

Handling insufficient credits

When your balance can't cover a lookup, the API returns 402 with your current credit_balance. Watch for this and prompt a top-up — and consider enabling low-balance warnings.