Errors & retries

Every error tells you what went wrong, whether it is worth retrying and what to do next, in a machine-readable form. This page explains the two error formats, how to decide what to do, and lists every error code with its recovery steps.

#Two formats, one vocabulary

Request errors stop a request before a valuation is recorded: invalid JSON or schema, authentication, scopes, countries, credits, idempotency conflicts, and rate or concurrency limits. They return a Problem document (RFC 9457 style) with Content-Type: application/problem+json:

{
  "type": "https://data-services.autouncle.com/docs/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The request does not match the valuation schema.",
  "errors": [
    { "pointer": "/vehicle/mileage/value", "message": "Invalid number value." }
  ],
  "fix": [
    "Correct the fields listed in errors (JSON Pointers into your request) and send the request again.",
    "Compare the request with the OpenAPI schema at /openapi.yaml."
  ],
  "request_id": "17cc70b0-1785-46af-afed-d5d65a22d4e2",
  "docs_url": "https://data-services.autouncle.com/docs/errors",
  "billable": false,
  "retryable": false
}

Recorded refusals and failures happen after a valuation has started: the vehicle could not be identified, mileage is missing, a service timed out. They return the normal valuation envelope as application/json, with status: "refused" or "failed", a val_… request_id, and the same Problem object nested in error. The HTTP status is the error's status. These outcomes are recorded, free and replayable. An example is in the valuations reference.

Both formats use the same codes, so your error handling can work on code alone.

#Error fields

#Deciding what to do

#Retries and replay

1. If you do not know whether a request completed (timeout, dropped connection), retry with the original idempotency key and the same body. A replay returns the recorded outcome, including a recorded refusal or failure, and never charges again.
2. If the request was rejected before it started (rate_limited, concurrency_limited, engine_busy, rate_limit_unavailable, request_in_progress), wait and retry with the same key. Nothing was recorded under it.
3. After a confirmed refusal or failure, use a new idempotency key for a deliberate fresh attempt. Replaying the old key only returns the same outcome.
4. Back off before retrying temporary failures: exponential delays with jitter, and a cap on attempts.
5. Never loop on validation, authentication, permission or credit errors. Fix the cause first.

retryable: true means a fresh attempt may succeed after the temporary condition clears. It does not mean the same idempotency key will run again.

Never log Authorization headers or full API keys. Log the request_id instead.

#Concurrency and capacity

Valuations run with a limited number of concurrent requests per workspace, per market and across the platform. When no slot frees up within about two seconds, the request is rejected before anything is reserved, charged or recorded:

• concurrency_limited (429): your workspace already has the maximum number of valuations in progress. Lower your parallelism.
• engine_busy (503, service valuation_engine): the market or the platform is at capacity. Back off.

Both are retryable and carry retry_after. Retry with the same idempotency key and body. Test-mode valuations have their own per-workspace limit and never use live capacity. See rate & concurrency limits.

#Dependency failures

Some valuations call other services: image retrieval, automated interpretation of text and photos, and the valuation scorer. They are called only when needed, within one processing budget (see how valuations work).

• Timeouts return 504: request_timeout, resolution_timeout, image_timeout, engine_timeout.
• Unavailability returns 503: resolution_unavailable, image_unavailable, engine_unavailable.
• Invalid upstream output returns 502: resolution_invalid_response, engine_invalid_response. An image that cannot be read is skipped with an image_skipped warning instead; images_unreadable and image_invalid_response stay in the catalogue for compatibility but are no longer returned.

Each failure names the service, includes recovery hints and the request ID, stops scoring and releases the reserved credit. Invalid image data or an unsafe image URL that you supplied is your input, not an outage: that image is skipped with an image_skipped warning and the request goes on with the rest.

A valid service result that simply contains no usable evidence is not a failure; the valuation continues and reports unused input in warnings.

engine_misconfigured (503, retryable: false) means the market's valuation service is not set up correctly on AutoUncle's side. Retrying will not help until it is fixed; contact support with the request ID. No credit is used.

#Errors over MCP

MCP tool calls use the same codes and payloads:

• A refused or failed valuation, or a request error inside a tool call, returns a normal tool result with isError: true. Its structured content (and the JSON text content) is the same valuation envelope or Problem as REST, including retry_after where it applies. MCP has no response headers, so retry_after is the only delay signal.
• An authentication failure on /mcp (missing, invalid or revoked key or token) returns HTTP 401 with a JSON-RPC error: message is the error code, such as invalid_api_key, and data is the Problem. The response also carries a WWW-Authenticate header that points OAuth-capable clients at the protected-resource metadata.

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "invalid_api_key",
    "data": { "code": "invalid_api_key", "status": 401, "retryable": false, "fix": ["Check that the full key is configured, without spaces or quotes, and that it belongs to this deployment.", "Create a new key in the console if it was revoked or lost."] }
  }
}

The data object above is shortened.

#Error codes

Every code the API can return, generated from the error catalogue. invalid_invitation and email_verification_required occur only in console invitation flows.

#400 Bad Request

#country_required

Include country, the valuation market, in the request.

HTTP 400 · not retryable

How to recover:

• Add country with an ISO market code from GET /v1/catalogue/countries.

#invalid_request

Send a request matching the documented schema.

HTTP 400 · not retryable

How to recover:

• Correct the fields listed in errors (JSON Pointers into your request) and send the request again.
• Compare the request with the OpenAPI schema at /openapi.yaml.

#unsupported_country

Choose a supported ISO country code.

HTTP 400 · not retryable

How to recover:

• Use an ISO 3166-1 alpha-2 market code from GET /v1/catalogue/countries, such as DK, DE or GB.

#401 Unauthorized

#invalid_api_key

Supply a valid AutoUncle Data Services API key.

HTTP 401 · not retryable

How to recover:

• Check that the full key is configured, without spaces or quotes, and that it belongs to this deployment.
• Create a new key in the console if it was revoked or lost.

#key_revoked

This key has expired or been revoked. Create a new key.

HTTP 401 · not retryable

How to recover:

• Create a new key in the console under API keys and update your integration's secret.

#unauthenticated

Supply an API key as a Bearer token.

HTTP 401 · not retryable

How to recover:

• Send the key as Authorization: Bearer <key>. Keys are created in the console under API keys.

#402 Payment Required

#insufficient_credits

The organization has no credits available. Contact sales for a package.

HTTP 402 · not retryable

How to recover:

• Use a test key for free simulated valuations while you wait.
• Ask a workspace owner to request a credit package; credits appear under Billing.

#key_spend_limit_reached

This API key has reached its monthly credit limit.

HTTP 402 · not retryable

How to recover:

• Ask a workspace owner or admin to raise this key's monthly credit limit, or use another key.
• The limit resets at the start of next month.

#403 Forbidden

#country_not_enabled

This country is not enabled for this organization or key.

HTTP 403 · not retryable

How to recover:

• Check allowed_countries in GET /v1/account for this key.
• Use a key that allows this market, or ask an owner or admin to enable it for the workspace.

#email_verification_required

Verify the email address matching this invitation before accepting it.

HTTP 403 · not retryable

How to recover:

• Sign in with the invited address and verify it from the email we sent, then open the invitation again.

#insufficient_scope

Use a key with the required scope.

HTTP 403 · not retryable

How to recover:

• Create a key with the scope this call needs (valuations:write, valuations:read, catalogue:read, account:read or vehicles:read).

#organization_pending

This workspace is waiting for AutoUncle to approve it.

HTTP 403 · not retryable

How to recover:

• Wait for AutoUncle to approve the workspace; the console shows when it is approved.
• Contact AutoUncle if you have not heard from us within two working days.

#organization_suspended

This organization is inactive. Contact support.

HTTP 403 · not retryable

How to recover:

• Contact AutoUncle support. Requests are refused until the workspace is reactivated.

#404 Not Found

#not_found

The requested resource was not found.

HTTP 404 · not retryable

How to recover:

• Check the identifier and that it belongs to this workspace and mode; test and live results are separate.

#unknown_catalogue_id

The catalogue ID is unknown. Fetch current IDs from the catalogue API.

HTTP 404 · not retryable

How to recover:

• Look the vehicle up again through the catalogue endpoints and send the IDs they return.
• If you cache catalogue IDs, refresh the cache when GET /v1/catalogue/version changes.

#409 Conflict

#idempotency_conflict

This idempotency key was used with different input. Choose a new key.

HTTP 409 · not retryable

How to recover:

• Use the same key only with the original request body. Choose a new key for a different valuation attempt.

#request_in_progress

A request with this idempotency key is still running. Retry later with the same key.

HTTP 409 · retryable

How to recover:

• Wait briefly, then retry identical input with the same idempotency key.

#413 Content Too Large

#payload_too_large

The request exceeds the maximum supported size of 1 MB.

HTTP 413 · not retryable

How to recover:

• Reduce the request below 1 MB: shorten the description, send fewer or smaller images, or use image URLs.

#422 Unprocessable Content

#catalogue_id_conflict

The catalogue IDs do not describe the same vehicle hierarchy.

HTTP 422 · not retryable

How to recover:

• Send IDs from a single catalogue path (brand → model → generation → drivetrain), or send only the lowest level you know.
• Remove make or model text that names a different vehicle than the IDs.

#images_unreadable

Provide readable supported images.

HTTP 422 · not retryable

How to recover:

• Send public HTTPS image URLs or base64 data with media_type (JPEG, PNG, WebP or GIF, 8 MB at most).

#invalid_invitation

The invitation has expired or has already been used or revoked.

HTTP 422 · not retryable

How to recover:

• Ask a workspace owner or admin to resend the invitation; each resend replaces the previous link.

#lookup_country_unsupported

Registration-plate lookups are not available for this country.

HTTP 422 · not retryable

How to recover:

• Look up plates only in a supported country (currently DK). The reason field says whether the country has no register connected yet (no_registry) or is excluded by policy (excluded_by_policy).
• No credit was used.

#missing_mileage

Supply the actual mileage in vehicle.mileage, or explicitly set options.allow_mileage_estimation to true to use a fixed 96,000 km baseline assumption.

HTTP 422 · not retryable

How to recover:

• Supply vehicle.mileage with its value and unit.
• If a fixed baseline assumption is acceptable, set options.allow_mileage_estimation to true. Strict resolution still requires actual mileage.
• This refusal is recorded under its idempotency key: send the corrected request with a new key.

#precision_below_minimum

Provide more attributes or lower the requested minimum precision.

HTTP 422 · not retryable

How to recover:

• Add the attributes listed in improve_precision, such as catalogue drivetrain_id, or lower options.min_precision.
• No credit was used.

#selling_time_unsupported_market

Selling-time forecasts are not available for this market.

HTTP 422 · not retryable

How to recover:

• Send the request for a market listed in the selling-time documentation, or use POST /v1/valuations for a valuation alone.
• No credit was used.

#unsupported_vehicle

This type of vehicle is not supported.

HTTP 422 · not retryable

How to recover:

• See reason for the input that excludes the vehicle. Remove a flag only if it does not apply to this vehicle.
• Vehicles outside the market's model (such as damaged or opposite drive side) cannot be valued.

#vehicle_not_identified

Provide more vehicle attributes or select catalogue IDs.

HTTP 422 · not retryable

How to recover:

• Supply make and model, or pick catalogue IDs from GET /v1/catalogue/search.
• Strict resolution also needs the registration year and actual mileage.

#vehicle_out_of_range

The vehicle is outside the supported valuation range.

HTTP 422 · not retryable

How to recover:

• Check the registration year (1900 to next year) and mileage (zero or more, with the correct unit).

#429 Too Many Requests

#concurrency_limited

Too many valuations are running at the same time for this organization.

HTTP 429 · retryable

How to recover:

• Wait for the Retry-After delay (retry_after seconds), then retry the same request with the same idempotency key. The request was not started and no credit was used.
• Limit the number of valuations your integration sends in parallel.

#rate_limited

The request rate limit was reached. Retry after the current minute.

HTTP 429 · retryable

How to recover:

• Wait for the rate limit to reset, then retry the same request with its original idempotency key.

#test_limit_reached

This workspace has used its fair-use allowance of test-key requests for now.

HTTP 429 · retryable

How to recover:

• Test keys are for building and testing an integration, not for checking real vehicles. Use a live key for production traffic.
• Wait retry_after seconds for the window to reset. GET /v1/account does not count against this allowance.
• Contact AutoUncle if your test suite needs a higher allowance.

#500 Internal Server Error

#internal_error

The valuation could not be completed. Contact support with the request ID.

HTTP 500 · not retryable

How to recover:

• Contact support with the request ID. Do not repeatedly retry unchanged input.

#502 Bad Gateway

#engine_invalid_response

The valuation service returned an invalid response.

HTTP 502 · retryable · service valuation_engine

How to recover:

• Retry later after the service recovers.
• Reuse the original idempotency key only when the outcome is unknown. After a recorded failure, use a new key for a fresh attempt.

#image_invalid_response

The image service returned an invalid response.

HTTP 502 · retryable · service image_fetch

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#resolution_invalid_response

Vehicle interpretation returned an invalid response.

HTTP 502 · retryable · service vehicle_resolution

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#503 Service Unavailable

#engine_busy

The valuation engine is at capacity. Retry after a short delay.

HTTP 503 · retryable · service valuation_engine

How to recover:

• Wait for the Retry-After delay (retry_after seconds), then retry the same request with the same idempotency key. The request was not started and no credit was used.

#engine_misconfigured

The valuation service for this market is not configured correctly.

HTTP 503 · not retryable · service valuation_engine

How to recover:

• This is a configuration problem on AutoUncle's side and retrying will not help until it is fixed. Contact support with the request ID.
• No credit was used.

#engine_unavailable

The valuation engine is temporarily unavailable. After a confirmed failed response, use a new idempotency key for a fresh attempt.

HTTP 503 · retryable

How to recover:

• Retry with the original idempotency key only when the outcome is unknown, such as a network interruption.
• After a confirmed failed response, retry later with a new idempotency key. The failed valuation did not consume a credit.

#image_unavailable

The image service is temporarily unavailable.

HTTP 503 · retryable · service image_fetch

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#lookup_unavailable

The vehicle lookup service is temporarily unavailable.

HTTP 503 · retryable · service vehicle_lookup

How to recover:

• Retry later after the service recovers. A failed lookup did not consume a credit.
• A failed lookup is never a "not found": do not treat it as an unknown vehicle.

#market_data_unavailable

Market figures are temporarily unavailable.

HTTP 503 · retryable · service market_data

How to recover:

• Retry later after the service recovers. The failed request did not consume a credit.

#rate_limit_unavailable

Request limiting is temporarily unavailable. Retry later.

HTTP 503 · retryable

How to recover:

• Retry after the indicated delay with the same idempotency key. The request was not started and no credit was used.

#resolution_unavailable

Vehicle interpretation is temporarily unavailable.

HTTP 503 · retryable · service vehicle_resolution

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#selling_time_unavailable

The selling-time forecast is temporarily unavailable.

HTTP 503 · retryable · service selling_time

How to recover:

• Retry later after the service recovers. The failed request did not consume a credit.
• Reuse the original idempotency key only when the outcome is unknown. After a recorded failure, use a new key for a fresh attempt.

#504 Gateway Timeout

#engine_timeout

The valuation service did not respond within its time budget.

HTTP 504 · retryable · service valuation_engine

How to recover:

• Retry later after the service recovers.
• Reuse the original idempotency key only when the outcome is unknown. After a recorded failure, use a new key for a fresh attempt.

#image_timeout

Image retrieval did not finish within its time budget.

HTTP 504 · retryable · service image_fetch

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#lookup_timeout

The vehicle lookup service did not respond within its time budget.

HTTP 504 · retryable · service vehicle_lookup

How to recover:

• Retry later after the service recovers. A failed lookup did not consume a credit.
• A failed lookup is never a "not found": do not treat it as an unknown vehicle.

#request_timeout

The valuation request exhausted its processing time budget.

HTTP 504 · retryable · service vehicle_resolution

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#resolution_timeout

Vehicle interpretation did not finish within its time budget.

HTTP 504 · retryable · service vehicle_resolution

How to recover:

• Retry later after the service recovers, or provide structured vehicle attributes instead.
• A recorded failure did not consume a credit. Reuse the original key only for an unknown outcome; use a new key for a deliberate fresh attempt after a recorded failure.

#selling_time_timeout

The selling-time forecast did not finish within its time budget.

HTTP 504 · retryable · service selling_time

How to recover:

• Retry later after the service recovers. The failed request did not consume a credit.
• Reuse the original idempotency key only when the outcome is unknown. After a recorded failure, use a new key for a fresh attempt.