Errors and retries

Handle CarHub API failures predictably.

All non-2xx responses share one envelope:

{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "param": null,
    "doc_url": "https://docs.trycarhub.com/errors/rate_limit_exceeded",
    "request_id": "req_2Kd8xQmPvL4T"
  }
}

Use type for broad program flow and code for precise handling. New codes can be added, so handle unknown codes as their known type.

Status	Typical code	What to do
400	missing_input, wait_not_supported	Correct the request. Do not blindly retry.
401	invalid_api_key	Replace or restore the credential.
402	insufficient_credits	Add credits, then submit again only if the original request did not create a job.
403	scope_not_granted	Use a key with the needed family scope or adjust permissions.
404	job_not_found	Check the identifier and credential mode.
409	idempotency_key_reuse	Generate a new key for a deliberately new payload.
429	rate_limit_exceeded	Wait for Retry-After, add jitter, then retry.
500	internal_error	Retry with the same idempotency key; quote request_id if it persists.

Failed jobs

A submission can be accepted and later finish as failed. Inspect the job’s error field. Model failures are distinct from request errors; a processing failure releases the reservation rather than charging successful inference.

Log request_id, the job ID and the endpoint slug together. Those three values make a support investigation much faster.