This page lists the error codes specific to the Courier API. The error response shape, the rule to branch on the code field, and the platform-wide codes (such as unauthenticated, forbidden, validation_failed, and rate_limit_exceeded) are documented in Authentication. The codes below are in addition to those, and they follow the same envelope.
Courier error codes
These codes are part of the public contract: new codes may be added over time, but existing rows never change their meaning. Handle a code you do not recognize gracefully rather than failing hard.
| Code | HTTP | When it occurs |
|---|---|---|
quote_not_found |
404 | The referenced quote does not exist. |
quote_expired |
409 | The quote is no longer valid and cannot be used to book. |
quote_already_executed |
409 | The quote has already been turned into a trip. |
trip_type_not_supported |
400 | The requested trip type is not supported for quote execution. |
trip_not_found |
404 | The referenced trip does not exist. |
trip_state_conflict |
409 | The trip is in a state that does not allow this operation — for example, canceling a trip that has already completed or cannot be canceled in its current state, or requesting an invoice for a trip that is not completed, was canceled, or had no driver assigned. |
trip_rating_not_allowed |
403 | Rating is not allowed for this trip. |
vehicle_not_supported |
400 | The requested vehicle is not recognized or not supported. |
vehicle_not_available |
400 | The requested vehicle is not available at the pickup location. |
service_not_available |
400 | The pickup location is outside any supported coverage area. |
insufficient_wallet_balance |
400 | The merchant wallet balance is insufficient. Courier trips bill the merchant wallet. |
service_unavailable |
502 | The service is temporarily unavailable. Safe to retry with backoff. |
internal_error |
500 | An unexpected server error occurred. Safe to retry with backoff. |
Handling validation errors
A validation_failed response (a platform code, see Authentication) carries the failing fields in details, so you can point the caller at exactly what to fix:
{
"error": "BadRequestError",
"message": "Request validation failed.",
"code": "validation_failed",
"details": [
{ "field": "pickup.lat", "message": "Required" },
{ "field": "dropoffs", "message": "Must contain at least one item" }
]
}Retrying
Treat 4xx codes as problems with the request itself: fix the request rather than retrying. For the Courier-specific codes, that means correcting the quote, trip, vehicle, location, or wallet condition named by the code. The retryable cases are the server-side errors service_unavailable (502) and internal_error (500) above, plus rate_limit_exceeded (429), which is covered in API Basics. Retry these with backoff rather than resending immediately.