Get started

Errors

Errors are plain JSON with a stable code to branch on and a message a person can read.

The format

json

HTTP/1.1 409 Conflict
X-Request-Id: req_5c1f0a9e3b7d2c4a81

{
  "error": {
    "code": "unavailable",
    "message": "This car was just booked by someone else.",
    "requestId": "req_5c1f0a9e3b7d2c4a81"
  }
}

code is stable: branch on it. message is written for people and is safe to show; its wording can improve, so do not match on it. requestId is for support.

Codes

HTTP	code	What it means	What to do
400	`invalid`	Something in the request is wrong: a missing field, a bad date, a price that is not whole naira. The message names it.	Fix the request. Do not retry unchanged.
401	`unauthorized`	The API key is missing, malformed or revoked.	Check the Authorization header and the key.
402	`payment`	We could not start the payment.	Try again in a moment; the car is released.
403	`forbidden`	This key may not do that: a live key before approval, a fleet call on a marketplace plan, a money call with our own website’s key, a sandbox call with a live key.	Check GET /me → capabilities.
404	`not_found`	No such thing, or it belongs to someone else (we do not say which).	Check the id or reference.
409	`unavailable`	The car is not free for those dates any more.	Offer another car or other dates.
409	`conflict`	It cannot be done in the current state: cancelling a completed booking, a second listing for a car, a period that overlaps.	Read the booking’s status first.
429	`rate_limited`	More than 120 requests a minute.	Wait RateLimit-Reset seconds, then retry.
500	`server_error`	Something went wrong on our side.	Retry with backoff, then contact us with the requestId.

When a booking fails

These are the ones you will meet. All are safe to show your customer as written.

Situation	Answer
Two customers book the same car	409 unavailable (“This car was just booked by someone else.”). Nothing was created for the loser.
Dates outside the owner’s availability, or less than 2 hours away	409 unavailable, or a quote with available: false and a reason (outside_availability, too_soon).
The customer’s licence expires before the rental ends	400 invalid (“The driver’s licence expires before the rental ends.”).
The customer does not pay within about 20 minutes	The booking becomes expired and the car is released. A webhook booking.expired tells you.
A repeated request with the same Idempotency-Key	201 again with the same booking. Not an error.
Cancelling after the rental started	409 conflict. Only unpaid and confirmed bookings can be cancelled.

Handling errors

A good pattern

Treat 5xx and 429 as try again later, 409 as offer an alternative, and every other 4xx as a bug in your request or a stale id: log it with the requestId. See the retry helper under rate limits.