Guides: Errors
Errors
Every error from the Motorbay API has the same shape, so one error handler covers the whole API.
The shape of an error
Errors are RFC 9457 problem details, sent as application/problem+json:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "Vehicle not found",
"status": 404,
"instance": "/v1/vehicles/plate/AB12345",
"code": "VehicleNotFound",
"requestId": "0HN7Q3C2V4K1M:00000001",
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}| Field | What it is |
|---|---|
status |
The HTTP status, repeated in the body |
code |
What went wrong, in PascalCase. Branch on this and on status |
title |
A short summary. The same for every error with that code |
detail |
What happened this time, in words you can show a user. Not always present |
instance |
The path you called |
requestId |
The same value as the X-Request-Id header |
traceId |
Our internal trace. Send it with the request ID if you contact us |
errors |
On ValidationFailed only. See below |
Branch on status and code, never on title or detail: the text can change, and a published code does not. Handle codes you don't know by their status, since we may add codes for new situations.
Language
Send Accept-Language: da and the API writes title and detail in Danish. Without the header, or with any language other than Danish, they are in English. The Content-Language header on the answer says which language was used. The code, the status and the keys in errors are the same in both languages. The messages inside errors are always in English.
X-Request-Id
Every response carries an X-Request-Id header, successful or not. On an error, the body repeats it as requestId. Log it. It's the first thing support asks for, and it lets us find your request.
Every error code
| Status | Code | When | What to do |
|---|---|---|---|
| 400 | ValidationFailed |
A parameter is malformed or out of range | Fix the request. The same request fails again |
| 400 | WebhookUrlNotAllowed |
A webhook endpoint's URL can't receive deliveries: it isn't https on port 443, or isn't a public address. detail says which |
Use another URL |
| 401 | ApiKeyMissing |
No X-Api-Key header |
Send the header |
| 401 | ApiKeyInvalid |
The key is unknown, revoked, expired, or from the other environment | Check the key, or create a new one |
| 402 | PaymentRequired |
The key's paid subscription is in a state we can't confirm | Open the billing portal from your account page, or email support |
| 403 | PlanUpgradeRequired |
Watching a vehicle or registering a webhook endpoint on the Free plan | Choose a paid plan |
| 404 | VehicleNotFound |
No vehicle with that ID, VIN or registration number | Don't retry now. The vehicle may appear after a later import |
| 404 | MakeNotFound |
No make with that ID | Check the ID |
| 404 | ModelNotFound |
No model with that ID under that make | Check the IDs |
| 404 | VariantNotFound |
No variant with that ID under that model | Check the IDs |
| 404 | DesignationTypeNotFound |
No designation type with that ID under that model | Check the IDs |
| 404 | ColorNotFound |
No color with that ID | Check the ID |
| 404 | KindNotFound |
No kind with that ID | Check the ID |
| 404 | UsageNotFound |
No usage with that ID | Check the ID |
| 404 | EmissionStandardNotFound |
No emission standard with that ID | Check the ID |
| 404 | FuelTypeNotFound |
No fuel type with that ID | Check the ID |
| 404 | BlockingReasonNotFound |
No blocking reason with that ID | Check the ID |
| 404 | PermitTypeNotFound |
No permit type with that ID | Check the ID |
| 404 | EquipmentNotFound |
No equipment with that ID | Check the ID |
| 404 | WatchNotFound |
You don't watch that vehicle | Check the vehicle ID |
| 404 | WebhookEndpointNotFound |
You have no webhook endpoint with that ID | Check the ID |
| 404 | RouteNotFound |
No such path | Check the URL and the /v1 prefix |
| 405 | MethodNotAllowed |
A method the path doesn't take, such as POST on a vehicle. The API reference lists each path's methods |
Use a method in the Allow header |
| 409 | WatchLimitReached |
You watch as many vehicles as your plan allows. limit says how many |
Stop watching one, or move to a larger plan |
| 409 | EndpointLimitReached |
You have as many webhook endpoints as your plan allows. limit says how many |
Delete one, or move to a larger plan |
| 413 | PayloadTooLarge |
A POST /v1/vehicles/plates body over 64 KB |
Send at most 500 plates per call |
| 429 | RateLimitExceeded |
More than 60 requests this minute with this key | Wait the Retry-After seconds, then retry |
| 429 | QuotaExceeded |
The plan's requests for this month are used up. On Free, that is the whole quota. For an account that hasn't verified a card or phone number, it can be the starter lookups: then verificationRequired is true |
Upgrade the plan, or wait. Retry-After runs to the start of next month (UTC). With verificationRequired, verify the account at verifyUrl instead: no month resets the starter lookups, so there is no Retry-After |
| 429 | FreeCapacityExhausted |
The Free plan has used its capacity for today, across all accounts. Your own quota is not the problem | Wait. Retry-After runs to 00:00 UTC. Paid plans aren't held to it |
| 500 | InternalError |
A fault on our side | Retry with the backoff below. If it keeps failing, send us the requestId |
| 503 | DatasetNotLoaded |
GET /v1/dataset before the first import has finished |
Try again later |
| 503 | ServiceUnavailable |
Your API key, or on watches and webhooks your account's plan, couldn't be checked just now. The key is not the problem | Wait the Retry-After seconds, then retry |
A list endpoint under a parent, such as /v1/makes/{makeId}/models, answers 404 with the parent's code (MakeNotFound) when the parent doesn't exist.
Validation errors
A 400 with ValidationFailed says which rule failed in errors, with a message for each:
{
"title": "The request is not valid",
"status": 400,
"code": "ValidationFailed",
"errors": {
"PageSizeOutOfRange": ["Page size must be at least 1 and at most 50."]
}
}The keys in errors are these rules:
| Rule | When |
|---|---|
PageOutOfRange |
page is below 1, or past the last page of a non-empty result |
PageSizeOutOfRange |
pageSize is below 1 or above the endpoint's maximum |
SortByInvalid |
sortBy isn't one of the documented values |
SearchTooDeep |
page × pageSize is more than 10,000 on vehicle search |
RegistrationStatusInvalid |
registrationStatus is not unknown, registered, deregistered or pending |
FirstRegisteredOnInvalid |
fromFirstRegisteredOn or toFirstRegisteredOn on vehicle search isn't a date as YYYY-MM-DD |
GroupByInvalid |
groupBy on /v1/statistics/vehicles names a field it can't group by, or one field twice |
GroupByTooMany |
groupBy names more than two fields |
AverageInvalid |
average on /v1/statistics/vehicles names a metric it can't average, one metric twice, or none |
LimitOutOfRange |
limit on /v1/statistics/vehicles is below 1 or above 1000 |
RegistrationNumberInvalid |
A registration number, in /v1/vehicles/plate/{plate} or ?registrationNumber=, has characters other than A to Z, 0 to 9, Æ, Ø and Å, or is longer than 10 once spaces and hyphens are removed |
IncludeInvalid |
An include value on a single-vehicle lookup isn't one of the documented parts or all. The message names the value |
UnitsInvalid |
units, power or mpg isn't one of its documented values, or mpg is sent without units=imperial. The message names the value |
ParameterInvalid |
A parameter that takes a number, such as makeId, fromModelYear, page or an {id} in the path, has something else, such as makeId=abc. The message names the parameter |
UrlRequired |
POST /v1/webhooks/endpoints has no url |
DescriptionTooLong |
A webhook endpoint's description is over 200 characters |
In the batch plate lookup (POST /v1/vehicles/plates) a plate that isn't valid is not a 400. It is an item with found: false and error.code InvalidPlate, and the rest of the call is answered. A valid plate no vehicle has is an item with error.code VehicleNotFound. Only a body that isn't {"plates": [...]} with 1 to 500 strings is a 400 with ValidationFailed, and a body over 64 KB is a 413 with PayloadTooLarge.
Responses that aren't errors
- 204 No Content. A vehicle's
/engine,/inspectionand/environmental-informationanswer204when the vehicle exists but the register has no such record for it. - An empty list. A search that matches nothing is a
200with"data": []andtotalCount0.
When to retry
Reads are safe to retry: every GET, and the batch lookup POST /v1/vehicles/plates. So are watching and unwatching a vehicle and deleting a webhook endpoint, which end the same however often you send them. A second DELETE answers 404, and the watch or endpoint is gone either way.
Two calls are not safe to repeat blind: creating a webhook endpoint and rotating its secret. Each makes a new secret, shown once. If one of them answers 500, or the answer never arrives, it may still have taken effect. List your endpoints first, then rotate the secret of the one you keep to get a secret you can use. See Watches and webhooks.
Retry only these:
- 429: wait the number of seconds in
Retry-After, then retry. - 500 or 503: back off 1, 2, then 4 seconds, and stop after three tries.
Never retry any other 4xx. The same request gets the same answer.
Didn't find the answer? Email support@motorbay.app.