Vejledninger: Fejl
Fejl
Alle fejl fra Motorbay API'et har samme form, så én fejlhåndtering dækker hele API'et.
Sådan ser en fejl ud
Fejl er RFC 9457 problem details, sendt som 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"
}| Felt | Hvad det er |
|---|---|
status |
HTTP-statussen, gentaget i svaret |
code |
Hvad der gik galt, i PascalCase. Forgren på den og på status |
title |
Et kort resumé. Det samme for alle fejl med den code |
detail |
Hvad der skete denne gang, i ord, du kan vise en bruger. Ikke altid med |
instance |
Den sti, du kaldte |
requestId |
Samme værdi som headeren X-Request-Id |
traceId |
Vores interne sporing. Send den med request-id'et, hvis du kontakter os |
errors |
Kun ved ValidationFailed. Se nedenfor |
Forgren på status og code, aldrig på title eller detail: teksten kan ændre sig, en offentliggjort code gør ikke. Håndtér koder, du ikke kender, ud fra deres status, for vi kan tilføje koder til nye situationer.
Sprog
Send Accept-Language: da, så skriver API'et title og detail på dansk. Uden headeren, eller med et andet sprog end dansk, er de på engelsk. Headeren Content-Language i svaret siger, hvilket sprog der blev brugt. code, status og nøglerne i errors er de samme på begge sprog. Beskederne i errors er altid på engelsk.
X-Request-Id
Alle svar har headeren X-Request-Id, uanset om de lykkes. Ved en fejl gentager svaret den som requestId. Log den. Det er det første, support spørger efter, og den lader os finde din forespørgsel.
Alle fejlkoder
| Status | Kode | Hvornår | Hvad du skal gøre |
|---|---|---|---|
| 400 | ValidationFailed |
En parameter er forkert formet eller uden for det tilladte | Ret forespørgslen. Den samme forespørgsel fejler igen |
| 400 | WebhookUrlNotAllowed |
Et webhook-endpoints URL kan ikke modtage leveringer: den er ikke https på port 443, eller den er ikke en offentlig adresse. detail fortæller hvilket |
Brug en anden URL |
| 401 | ApiKeyMissing |
Ingen X-Api-Key-header |
Send headeren |
| 401 | ApiKeyInvalid |
Nøglen er ukendt, tilbagekaldt, udløbet eller fra det andet miljø | Tjek nøglen, eller opret en ny |
| 402 | PaymentRequired |
Nøglens betalte abonnement er i en tilstand, vi ikke kan bekræfte | Åbn betalingsportalen fra din kontoside, eller skriv til support |
| 403 | PlanUpgradeRequired |
Overvågning af et køretøj eller registrering af et webhook-endpoint på Free-abonnementet | Vælg et betalt abonnement |
| 404 | VehicleNotFound |
Intet køretøj med det id, stelnummer eller registreringsnummer | Prøv ikke igen nu. Køretøjet kan dukke op efter en senere import |
| 404 | MakeNotFound |
Intet mærke med det id | Tjek id'et |
| 404 | ModelNotFound |
Ingen model med det id under det mærke | Tjek id'erne |
| 404 | VariantNotFound |
Ingen variant med det id under den model | Tjek id'erne |
| 404 | DesignationTypeNotFound |
Ingen typebetegnelse med det id under den model | Tjek id'erne |
| 404 | ColorNotFound |
Ingen farve med det id | Tjek id'et |
| 404 | KindNotFound |
Ingen art med det id | Tjek id'et |
| 404 | UsageNotFound |
Ingen anvendelse med det id | Tjek id'et |
| 404 | EmissionStandardNotFound |
Ingen euronorm med det id | Tjek id'et |
| 404 | FuelTypeNotFound |
Intet drivmiddel med det id | Tjek id'et |
| 404 | BlockingReasonNotFound |
Ingen blokeringsårsag med det id | Tjek id'et |
| 404 | PermitTypeNotFound |
Ingen tilladelsestype med det id | Tjek id'et |
| 404 | EquipmentNotFound |
Intet udstyr med det id | Tjek id'et |
| 404 | WatchNotFound |
Du overvåger ikke det køretøj | Tjek køretøjets id |
| 404 | WebhookEndpointNotFound |
Du har intet webhook-endpoint med det id | Tjek id'et |
| 404 | RouteNotFound |
Stien findes ikke | Tjek URL'en og præfikset /v1 |
| 405 | MethodNotAllowed |
En metode, stien ikke tager imod, fx POST på et køretøj. API-referencen viser hver stis metoder |
Brug en metode fra headeren Allow |
| 409 | WatchLimitReached |
Du overvåger så mange køretøjer, som dit abonnement tillader. limit fortæller hvor mange |
Stop med at overvåge et, eller skift til et større abonnement |
| 409 | EndpointLimitReached |
Du har så mange webhook-endpoints, som dit abonnement tillader. limit fortæller hvor mange |
Slet et, eller skift til et større abonnement |
| 413 | PayloadTooLarge |
En body til POST /v1/vehicles/plates på over 64 KB |
Send højst 500 nummerplader pr. kald |
| 429 | RateLimitExceeded |
Mere end 60 forespørgsler dette minut med denne nøgle | Vent de sekunder, Retry-After angiver, og prøv så igen |
| 429 | QuotaExceeded |
Abonnementets forespørgsler for denne måned er brugt. På Free er det hele kvoten. For en konto, der ikke har bekræftet et kort eller et telefonnummer, kan det være startopslagene. Så er verificationRequired true |
Opgradér abonnementet, eller vent. Retry-After løber til starten af næste måned (UTC). Med verificationRequired skal du i stedet bekræfte kontoen på verifyUrl. Ingen måned nulstiller startopslagene, så der er ingen Retry-After |
| 429 | FreeCapacityExhausted |
Free-abonnementet har brugt sin kapacitet for i dag på tværs af alle konti. Det er ikke din egen kvote, der er brugt | Vent. Retry-After løber til kl. 00.00 UTC. Betalte abonnementer er ikke omfattet |
| 500 | InternalError |
En fejl hos os | Prøv igen med pauserne nedenfor. Bliver det ved, så send os requestId |
| 503 | DatasetNotLoaded |
GET /v1/dataset, før den første import er færdig |
Prøv igen senere |
| 503 | ServiceUnavailable |
Din API-nøgle, eller ved overvågning og webhooks kontoens abonnement, kunne ikke kontrolleres lige nu. Nøglen er ikke problemet | Vent det antal sekunder, Retry-After angiver, og prøv igen |
Et listeendpoint under en overordnet ressource, fx /v1/makes/{makeId}/models, svarer 404 med den overordnedes kode (MakeNotFound), når den ikke findes.
Valideringsfejl
En 400 med ValidationFailed fortæller i errors, hvilken regel der fejlede, med en besked for hver:
{
"title": "The request is not valid",
"status": 400,
"code": "ValidationFailed",
"errors": {
"PageSizeOutOfRange": ["Page size must be at least 1 and at most 50."]
}
}Nøglerne i errors er disse regler:
| Regel | Hvornår |
|---|---|
PageOutOfRange |
page er under 1 eller efter sidste side i et resultat, der ikke er tomt |
PageSizeOutOfRange |
pageSize er under 1 eller over endpointets maksimum |
SortByInvalid |
sortBy er ikke en af de dokumenterede værdier |
SearchTooDeep |
page × pageSize er mere end 10.000 i køretøjssøgning |
RegistrationStatusInvalid |
registrationStatus er ikke unknown, registered, deregistered eller pending |
FirstRegisteredOnInvalid |
fromFirstRegisteredOn eller toFirstRegisteredOn i køretøjssøgningen er ikke en dato som YYYY-MM-DD |
GroupByInvalid |
groupBy på /v1/statistics/vehicles nævner et felt, der ikke kan grupperes efter, eller det samme felt to gange |
GroupByTooMany |
groupBy nævner mere end to felter |
AverageInvalid |
average på /v1/statistics/vehicles nævner et mål, der ikke kan beregnes gennemsnit af, det samme mål to gange, eller intet |
LimitOutOfRange |
limit på /v1/statistics/vehicles er under 1 eller over 1000 |
RegistrationNumberInvalid |
Et registreringsnummer, i /v1/vehicles/plate/{plate} eller ?registrationNumber=, har andre tegn end A til Z, 0 til 9, Æ, Ø og Å, eller er længere end 10, når mellemrum og bindestreger er fjernet |
IncludeInvalid |
En include-værdi på et opslag af ét køretøj er ikke en af de dokumenterede dele eller all. Beskeden nævner værdien |
UnitsInvalid |
units, power eller mpg er ikke en af de dokumenterede værdier, eller mpg er sendt uden units=imperial. Beskeden nævner værdien |
ParameterInvalid |
En parameter, der tager et tal, fx makeId, fromModelYear, page eller et {id} i stien, har noget andet, fx makeId=abc. Beskeden nævner parameteren |
UrlRequired |
POST /v1/webhooks/endpoints har ingen url |
DescriptionTooLong |
Et webhook-endpoints description er over 200 tegn |
I opslaget af mange nummerplader (POST /v1/vehicles/plates) er en ugyldig nummerplade ikke en 400. Den er et element med found: false og error.code InvalidPlate, og resten af kaldet bliver besvaret. En gyldig nummerplade, som intet køretøj har, er et element med error.code VehicleNotFound. Kun en body, der ikke er {"plates": [...]} med 1 til 500 tekststrenge, giver 400 med ValidationFailed, og en body over 64 KB giver 413 med PayloadTooLarge.
Svar, der ikke er fejl
- 204 No Content. Et køretøjs
/engine,/inspectionog/environmental-informationsvarer204, når køretøjet findes, men registret ikke har sådan en post for det. - En tom liste. En søgning uden resultater er
200med"data": []ogtotalCount0.
Hvornår du skal prøve igen
Opslag kan trygt gentages: alle GET, og batchopslaget POST /v1/vehicles/plates. Det samme gælder at overvåge og stoppe overvågningen af et køretøj og at slette et webhook-endpoint, som ender ens, uanset hvor mange gange du sender dem. Et andet DELETE svarer 404, og overvågningen eller endpointet er væk under alle omstændigheder.
To kald skal du ikke gentage i blinde: at oprette et webhook-endpoint og at skifte dets nøgle. Hvert kald laver en ny nøgle, som kun vises én gang. Svarer et af dem 500, eller kommer svaret aldrig, kan det stadig være gennemført. Se dine endpoints først, og skift så nøglen på det, du beholder, for at få en nøgle, du kan bruge. Se Overvågning og webhooks.
Prøv kun igen ved disse:
- 429: vent det antal sekunder,
Retry-Afterangiver, og prøv så igen. - 500 eller 503: vent 1, 2 og så 4 sekunder, og stop efter tre forsøg.
Prøv aldrig igen ved andre 4xx. Den samme forespørgsel får det samme svar.
Fandt du ikke svaret? Skriv til support@motorbay.app.