Error Handling

The VCDP API uses RFC 7807 Problem Details for error responses, providing structured and actionable error information.

Error response format

All error responses use application/problem+json content type:

{
  "type": "/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The request payload contains invalid fields",
  "instance": "/v1/vehicles/INVALID-VIN",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "violations": [
    {
      "field": "vin",
      "rejectedValue": "INVALID-VIN",
      "message": "must be exactly 17 characters"
    }
  ]
}

Common HTTP status codes

Status	Meaning	Action
400	Bad Request	Check request parameters and payload
401	Unauthorized	Refresh your access token or re-authenticate
404	Not Found	Verify the resource identifier exists
429	Too Many Requests	Wait and retry with backoff
500	Internal Server Error	Retry later; report if persistent

Correlation ID

Every response includes an X-Correlation-ID header. Include this when contacting support to help trace issues.

Retry strategy

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    if (response.status >= 500 && attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}