Error Handling

The API uses standard HTTP status codes and returns error details in a consistent JSON format.

Error Response Format

{
  "error": "Human-readable error message",
  "details": {
    "field": "Additional context"
  }
}

The details field is optional and provides additional context when available (e.g., validation field errors).

HTTP Status Codes

Status	Meaning
200	Success
201	Resource created
400	Bad Request — Invalid input, missing fields, validation errors
401	Unauthorized — Missing or invalid API key
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
409	Conflict — State conflict (e.g., vehicle no longer available)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our end

Common Errors

Validation Errors (400)

When request body validation fails:

{
  "error": "Validation failed",
  "details": {
    "pickupDate": "Invalid date format",
    "email": "Email is required"
  }
}

Vehicle Unavailable (409)

When trying to book a vehicle that's no longer available:

{
  "error": "Vehicle is no longer available for the selected dates"
}

Session Expired (404)

When a quote session has expired:

{
  "error": "Session not found or expired"
}

Booking Not Cancellable (400)

When trying to cancel a booking that can't be cancelled:

{
  "error": "Booking cannot be cancelled: within cancellation window"
}

Stripe Not Configured (400)

When using pay_now/deposit mode without Stripe:

{
  "error": "Online payments are not available"
}

Handling Errors

const response = await fetch('/api/v1/quotes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer crb_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ... }),
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}: ${error.error}`);

  if (error.details) {
    // Handle field-level validation errors
    Object.entries(error.details).forEach(([field, message]) => {
      console.error(`  ${field}: ${message}`);
    });
  }
}

On this page