API error codes

Last updated: 6 November 2026

Every error the DealerPricing developer API sends has a code you can match on, a plain message, and the same request id as the X-Request-Id header. Each error also says whose side the problem is on (type), whether the same request can succeed later (retryable), whether you were charged (charged, always false unless something went wrong with a refund), and links back to this page (doc_url). Failed requests are never charged.

API version 2 from 1 February 2027: new error codes and corrected responses

We are replacing codes that had several causes with codes that have one, and correcting response shapes. Accounts created from 5 November 2026, and accounts that never had a live key, already get version 2. Accounts that had a live key keep version 1 until 1 February 2027, then move to version 2. Until 2 May 2027 (90 days after the switch) you can still ask for version 1; after that it stops. You can switch now: see how to choose.

What version 2 changes

Error codes: one cause per code, as listed on this page, with the HTTP statuses described below.
Responses: corrected shapes on the vehicle, market and service history endpoints. Fields that are never filled are removed, fields that were always empty on live answers are no longer sent, and dates are YYYY-MM-DD (a moment in time stays a full timestamp). Each endpoint in the API reference lists what differs in version 1, and the OpenAPI file publishes both shapes.
Unchanged in both versions: fixes that keep every field name, type and format, and new fields, reach every account straight away. See the changelog.
Switch now: send DP-Error-Codes: 2 on a request, or choose version 2 on the API version 2 card of your developer dashboard. You can switch back until 1 February 2027.

What an error looks like

Version 2 (the new codes). legacy_code carries the version 1 code until 2 May 2027.

{
  "success": false,
  "error": {
    "code": "VALUATION_NOT_AVAILABLE",
    "message": "We hold no valuation for this vehicle. ...",
    "details": { "request_id": "req_...", "cost_pence": 0, "balance_pence": 984 },
    "type": "not_available",
    "retryable": false,
    "charged": false,
    "doc_url": "https://www.dealerpricing.co.uk/developer/errors#VALUATION_NOT_AVAILABLE",
    "legacy_code": "VEHICLE_NOT_FOUND"
  },
  "meta": { "request_id": "req_...", "error_codes_version": 2 }
}

Version 1 (the current codes). Nothing was removed or renamed; the extra fields were added, and next_code is the version 2 code the same request gets.

{
  "success": false,
  "error": {
    "code": "VEHICLE_NOT_FOUND",
    "message": "We hold no valuation for this vehicle. ...",
    "details": { "request_id": "req_...", "cost_pence": 0, "balance_pence": 984 },
    "type": "not_available",
    "retryable": false,
    "charged": false,
    "doc_url": "https://www.dealerpricing.co.uk/developer/errors#VALUATION_NOT_AVAILABLE",
    "next_code": "VALUATION_NOT_AVAILABLE"
  },
  "meta": { "request_id": "req_...", "error_codes_version": 1 }
}

HTTP statuses: version 2 answers 403 (not 401) for a disabled account or an unverified email, 503 (not 502) when a data source's daily limit is reached, and 400 (not 404) on the market endpoints for a registration that cannot exist. Version 1 keeps the statuses it always sent.

Choosing a version

For one request: send the header DP-Error-Codes: 2 (new codes) or DP-Error-Codes: 1 (current codes). The header wins over the account setting.
For every request on the account: the API version 2 card on your developer dashboard (shown to accounts that had a live key before 5 November 2026). The same setting chooses the error codes and the response shapes.
Every answer says which version it used: the DP-Error-Codes response header, and meta.error_codes_version on errors.
From 2 May 2027, version 1 no longer exists and a request for it is ignored.

Error types

authenticationYour side

The API key is missing, not recognised or revoked.

permissionYour side

The key is recognised but this call is not allowed for the account or key.

invalid_requestYour side

Something in the request needs changing before it can succeed.

billingYour side

The account cannot pay for this call.

limitYour side

A limit on your key, package or account was reached. It resets on its own.

not_foundAbout the vehicle

The vehicle or request you named does not exist in the data we use.

not_availableAbout the vehicle

The vehicle is known, but we hold no data of this kind for it.

source_errorOur side

A data source we use failed or will not answer us for now. You were not charged.

internalOur side

Something failed on our side. You were not charged.

Every code

Authentication

MISSING_API_KEY

HTTP 401Authentication

No API key sent

The request carried no API key.

What to do: Send your key in the X-API-Key header.
Retry: No (retryable: false)
Charged: No
Endpoints: All endpoints
Version 1 code: INVALID_API_KEY (HTTP 401)

INVALID_API_KEY

HTTP 401Authentication

API key not recognised

The key is not one of ours, or is not in the right format (dp_live_ or dp_sandbox_ followed by 48 characters).

What to do: Check the key was copied in full. Create a new key in the developer portal if needed.
Retry: No (retryable: false)
Charged: No
Endpoints: All endpoints
Version 1 code: INVALID_API_KEY (HTTP 401), INVALID_API_KEY_FORMAT (HTTP 401)

API_KEY_REVOKED

HTTP 401Authentication

API key revoked

This key was revoked and no longer works.

What to do: Create a new key in the developer portal and use that instead.
Retry: No (retryable: false)
Charged: No
Endpoints: All endpoints
Version 1 code: API_KEY_DISABLED (HTTP 401)

Permission

ACCOUNT_DISABLED

HTTP 403Permission

Developer account disabled

The developer account this key belongs to is disabled, so none of its keys work.

What to do: Contact support.
Retry: No (retryable: false)
Charged: No
Endpoints: All endpoints
Version 1 code: API_KEY_DISABLED (HTTP 401)

EMAIL_NOT_VERIFIED

HTTP 403Permission

Email not verified

Live keys work only once the account email address is verified. Sandbox keys work without it.

What to do: Open the verification email we sent, or ask for a new one in the developer portal.
Retry: After you verify your email (retryable: false)
Charged: No
Endpoints: All endpoints (live keys)
Version 1 code: EMAIL_NOT_VERIFIED (HTTP 401)

SANDBOX_NOT_SUPPORTED

HTTP 403Permission

No sandbox for this endpoint

This endpoint has no sandbox data, so sandbox keys cannot call it.

What to do: Use a live key.
Retry: No (retryable: false)
Charged: No
Endpoints: Live-only endpoints (none at present)
Version 1 code: New in version 2

Invalid request

MISSING_PARAMETER

HTTP 400Invalid request

Required field missing

A required field is missing. details.parameter names it.

What to do: Send the field named in details.parameter (for vehicle endpoints, vrm or vin).
Retry: No (retryable: false)
Charged: No
Endpoints: All vehicle and market endpoints, service history
Version 1 code: MISSING_PARAMETER (HTTP 400)

INVALID_PARAMETER

HTTP 400Invalid request

Field value not usable

A field has a value we cannot use, for example a callback_url that is not https. details.parameter names it when known.

What to do: Correct the value and send the request again.
Retry: No (retryable: false)
Charged: No
Endpoints: All endpoints
Version 1 code: INVALID_REQUEST (HTTP 400)

INVALID_VRM

HTTP 400Invalid request

Registration cannot exist

The registration is not 2 to 8 letters and digits, or the vehicle register refuses it as a registration that cannot exist.

What to do: Check the characters (for example O and 0, I and 1) and send it again without spaces.
Retry: No (retryable: false)
Charged: No
Endpoints: All vehicle and market endpoints
Version 1 code: INVALID_VRM (HTTP 400), INVALID_REQUEST (HTTP 400), VEHICLE_NOT_FOUND (HTTP 404)

INVALID_VIN

HTTP 400Invalid request

VIN cannot exist

The VIN is not 5 to 17 letters and digits without I, O or Q, or it was refused as a VIN that cannot exist. Service history needs all 17 characters.

What to do: Check the VIN and send it again.
Retry: No (retryable: false)
Charged: No
Endpoints: Decode, spec, valuation, provenance, service history
Version 1 code: INVALID_REQUEST (HTTP 400)

VIN_NOT_SUPPORTED

HTTP 400Invalid request

Endpoint needs a registration

This endpoint looks vehicles up by registration only. details.vin_endpoints lists the endpoints that take a VIN.

What to do: Send vrm instead of vin, or decode the VIN first to get the registration.
Retry: No (retryable: false)
Charged: No
Endpoints: Tax and MOT, market active, market sold, market insights, pricing insights
Version 1 code: INVALID_REQUEST (HTTP 400)

INVALID_REQUEST_ID

HTTP 400Invalid request

Request id not valid

The service history request id in the URL is not a valid id.

What to do: Use the request_id returned when the service history request was made.
Retry: No (retryable: false)
Charged: No
Endpoints: Service history status
Version 1 code: INVALID_REQUEST (HTTP 400)

Billing

INSUFFICIENT_BALANCE

HTTP 402Billing

Balance too low

Your balance plus any plan credit is below the price of this call. details.required_pence and details.balance_pence give the figures.

What to do: Top up in the developer portal, then send the request again.
Retry: After a top-up (retryable: false)
Charged: No
Endpoints: All priced endpoints
Version 1 code: INSUFFICIENT_BALANCE (HTTP 402)

Limit

RATE_LIMIT_EXCEEDED

HTTP 429Limit

Key rate limit reached

Too many calls on this key. details.window says which limit: second, minute or day.

What to do: Wait for the Retry-After header (seconds), then send the request again.
Retry: After details.retry_after_seconds (retryable: true)
Charged: No
Endpoints: All endpoints
Version 1 code: RATE_LIMIT_EXCEEDED (HTTP 429)

SANDBOX_DAILY_LIMIT_REACHED

HTTP 429Limit

Sandbox daily limit reached

The account has used its 1,000 sandbox calls for the day, across all its sandbox keys.

What to do: Wait for the reset (Retry-After header), or test with a live key.
Retry: After details.retry_after_seconds (retryable: true)
Charged: No
Endpoints: All endpoints (sandbox keys)
Version 1 code: RATE_LIMIT_EXCEEDED (HTTP 429)

PACKAGE_LIMIT_EXCEEDED

HTTP 429Limit

Package limit reached

Your package limit across all live keys on the account was reached.

What to do: Wait for the reset (Retry-After header), or move to a larger package.
Retry: After details.retry_after_seconds (retryable: true)
Charged: No
Endpoints: All priced endpoints
Version 1 code: PACKAGE_LIMIT_EXCEEDED (HTTP 429)

ENDPOINT_DAILY_CAP_REACHED

HTTP 429Limit

Endpoint daily cap reached

Your package's daily cap for this endpoint was reached.

What to do: Wait for the reset at midnight UK time (Retry-After header), or move to a larger package.
Retry: After midnight UK time (retryable: true)
Charged: No
Endpoints: Endpoints with a daily cap on your package
Version 1 code: ENDPOINT_DAILY_CAP_REACHED (HTTP 429)

TOO_MANY_OPEN_REQUESTS

HTTP 429Limit

Too many requests in progress

The account already has the most service history requests in progress at once (25).

What to do: Wait for some to finish (poll them or wait for the callbacks), then send the request again.
Retry: After one of your open requests finishes (retryable: true)
Charged: No
Endpoints: Service history
Version 1 code: RATE_LIMIT_EXCEEDED (HTTP 429)

Not found

VEHICLE_NOT_FOUND

HTTP 404Not found

Vehicle not found

No source we use knows this registration or VIN.

What to do: Check the registration or VIN. A very new, very old or recently changed registration may not be held yet.
Retry: No (retryable: false)
Charged: No
Endpoints: All vehicle and market endpoints
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

SANDBOX_VEHICLE_NOT_AVAILABLE

HTTP 404Not found

Not a sandbox test vehicle

Sandbox keys answer only for the published test vehicles.

What to do: Use a registration or VIN from GET /v1/sandbox/vrms, or a live key.
Retry: No (retryable: false)
Charged: No
Endpoints: All endpoints (sandbox keys)
Version 1 code: SANDBOX_VRM_NOT_ALLOWED (HTTP 404)

REQUEST_NOT_FOUND

HTTP 404Not found

No such request

There is no service history request with this id on your account.

What to do: Check the id. Requests made with another account cannot be read.
Retry: No (retryable: false)
Charged: No
Endpoints: Service history status
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

REQUEST_EXPIRED

HTTP 410Not found

Request expired

The service history request finished more than 7 days ago and can no longer be read.

What to do: Make a new service history request.
Retry: No (retryable: false)
Charged: No
Endpoints: Service history status
Version 1 code: REQUEST_EXPIRED (HTTP 410)

Not available

VALUATION_NOT_AVAILABLE

HTTP 404Not available

No valuation held

The vehicle is known, but we hold no valuation for it.

What to do: Other endpoints (decode, spec, tax and MOT) may still answer for this vehicle.
Retry: No (retryable: false)
Charged: No
Endpoints: Valuation
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

SPEC_NOT_AVAILABLE

HTTP 404Not available

No specification held

The vehicle is known, but we hold no factory specification for it.

What to do: Decode may still answer with the main vehicle details.
Retry: No (retryable: false)
Charged: No
Endpoints: Spec
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

HISTORY_NOT_AVAILABLE

HTTP 404Not available

History checks not available

The vehicle is known, but the history checks could not be answered for it.

What to do: Other endpoints may still answer for this vehicle.
Retry: No (retryable: false)
Charged: No
Endpoints: Provenance
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

MARKET_DATA_NOT_AVAILABLE

HTTP 404Not available

No market match

The vehicle is known, but we cannot match it to a model on the market, so there is nothing to compare it with.

What to do: Decode and valuation may still answer for this vehicle.
Retry: No (retryable: false)
Charged: No
Endpoints: Market active, market sold, market insights, pricing insights
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

SERVICE_HISTORY_NOT_AVAILABLE

HTTP 404Not available

Service history not available

The manufacturer service network does not recognise this vehicle, or the make is not covered.

What to do: Check the registration or VIN. Some makes and older vehicles have no digital service history.
Retry: No (retryable: false)
Charged: No
Endpoints: Service history
Version 1 code: VEHICLE_NOT_FOUND (HTTP 404)

Source error

SOURCE_UNAVAILABLE

HTTP 502Source error

Data source unavailable

A data source we use failed or did not answer in time. You were not charged.

What to do: Retry after a short wait. If it keeps happening, check the status page or contact support with the request id.
Retry: Yes, shortly (retryable: true)
Charged: No
Endpoints: All vehicle and market endpoints, service history
Version 1 code: UPSTREAM_ERROR (HTTP 502)

SOURCE_LIMIT_REACHED

HTTP 503Source error

Data source limit reached

A data source will not answer us again until its daily reset. This is our capacity, not yours, and you were not charged.

What to do: Retry later. Contact support with the request id if it lasts.
Retry: After the source resets (usually midnight UK time) (retryable: true)
Charged: No
Endpoints: Decode, spec, valuation, provenance and the market endpoints
Version 1 code: UPSTREAM_ERROR (HTTP 502)

Internal

INTERNAL_ERROR

HTTP 500Internal

Internal error

Something failed on our side, for example reading your balance. You were not charged.

What to do: Retry. If it keeps happening, contact support with the request id.
Retry: Yes (retryable: true)
Charged: No
Endpoints: All endpoints
Version 1 code: INTERNAL_ERROR (HTTP 500)

Warnings on successful answers

Some successful answers carry facts you should know about in meta.warnings. They are not errors: the answer is charged as normal. Warnings are sent in both versions.

"meta": {
  "request_id": "req_...",
  "cost_pence": 16,
  "warnings": [
    { "code": "PLATE_IN_RETENTION", "message": "This registration is on a retention certificate. ..." }
  ]
}

PLATE_IN_RETENTION

The registration is on a retention certificate. The data returned is for the last vehicle that carried it, which may not be the vehicle in front of you.

What to do: Compare the VIN in the answer with the vehicle before relying on the data.

Endpoints: Decode, spec, valuation, provenance

PARAMETER_IGNORED

A field you sent was not used (for example mileage that is not a positive number, rows above the maximum, or a match option that does not apply). parameter names it.

What to do: Correct the field if you meant it to change the answer.

Endpoints: Valuation, market active, market sold, pricing insights

Version 1 codes and what replaces them

The codes sent before 5 November 2026. They stay available as described above, and every version 2 error carries the matching one in legacy_code until 2 May 2027.

INVALID_API_KEY

No key sent, key not recognised.

Version 2: MISSING_API_KEY, INVALID_API_KEY

INVALID_API_KEY_FORMAT

Key not in the right format.

Version 2: INVALID_API_KEY

API_KEY_DISABLED

Key revoked, or the account disabled.

Version 2: API_KEY_REVOKED, ACCOUNT_DISABLED

ACCOUNT_DISABLED

Defined but never sent in version 1.

Version 2: ACCOUNT_DISABLED