# Error catalogue

Generated from the API error catalogue. Do not edit this file by hand.

Errors use application/problem+json; refused and failed valuations return the valuation envelope with a nested `error` in the same format. Match on `code`, never on `detail`. Never retry authentication, validation or credit failures unchanged.

Reuse the same idempotency key and body only when the outcome is unknown (network failure, timeout before a response) or when the error says the request was not started (`rate_limited`, `concurrency_limited`, `engine_busy`, `rate_limit_unavailable`, `request_in_progress`). A replay returns the original recorded outcome, including recorded failures. After a confirmed refused or failed result, use a new key for a deliberate fresh attempt, with bounded backoff for retryable codes.

Wait `retry_after` seconds (REST also sends `Retry-After`) when present.

| Code | HTTP | Retryable | Detail | Recovery |
| --- | --- | --- | --- | --- |
| `country_required` | 400 | no | Include country, the valuation market, in the request. | Add country with an ISO market code from GET /v1/catalogue/countries. |
| `invalid_request` | 400 | no | Send a request matching the documented schema. | 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` | 400 | no | Choose a supported ISO country code. | Use an ISO 3166-1 alpha-2 market code from GET /v1/catalogue/countries, such as DK, DE or GB. |
| `invalid_api_key` | 401 | no | Supply a valid AutoUncle Data Services API key. | 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` | 401 | no | This key has expired or been revoked. Create a new key. | Create a new key in the console under API keys and update your integration's secret. |
| `unauthenticated` | 401 | no | Supply an API key as a Bearer token. | Send the key as Authorization: Bearer <key>. Keys are created in the console under API keys. |
| `insufficient_credits` | 402 | no | The organization has no credits available. Contact sales for a package. | 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` | 402 | no | This API key has reached its monthly credit limit. | 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. |
| `country_not_enabled` | 403 | no | This country is not enabled for this organization or key. | 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` | 403 | no | Verify the email address matching this invitation before accepting it. | Sign in with the invited address and verify it from the email we sent, then open the invitation again. |
| `insufficient_scope` | 403 | no | Use a key with the required scope. | Create a key with the scope this call needs (valuations:write, valuations:read, catalogue:read, account:read or vehicles:read). |
| `organization_pending` | 403 | no | This workspace is waiting for AutoUncle to approve it. | 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` | 403 | no | This organization is inactive. Contact support. | Contact AutoUncle support. Requests are refused until the workspace is reactivated. |
| `not_found` | 404 | no | The requested resource was not found. | Check the identifier and that it belongs to this workspace and mode; test and live results are separate. |
| `unknown_catalogue_id` | 404 | no | The catalogue ID is unknown. Fetch current IDs from the catalogue API. | 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. |
| `idempotency_conflict` | 409 | no | This idempotency key was used with different input. Choose a new key. | Use the same key only with the original request body. Choose a new key for a different valuation attempt. |
| `request_in_progress` | 409 | yes | A request with this idempotency key is still running. Retry later with the same key. | Wait briefly, then retry identical input with the same idempotency key. |
| `payload_too_large` | 413 | no | The request exceeds the maximum supported size of 1 MB. | Reduce the request below 1 MB: shorten the description, send fewer or smaller images, or use image URLs. |
| `catalogue_id_conflict` | 422 | no | The catalogue IDs do not describe the same vehicle hierarchy. | 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` | 422 | no | Provide readable supported images. | Send public HTTPS image URLs or base64 data with media_type (JPEG, PNG, WebP or GIF, 8 MB at most). |
| `invalid_invitation` | 422 | no | The invitation has expired or has already been used or revoked. | Ask a workspace owner or admin to resend the invitation; each resend replaces the previous link. |
| `lookup_country_unsupported` | 422 | no | Registration-plate lookups are not available for this country. | 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` | 422 | no | 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. | 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` | 422 | no | Provide more attributes or lower the requested minimum precision. | 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` | 422 | no | Selling-time forecasts are not available for this market. | 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` | 422 | no | This type of vehicle is not supported. | 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` | 422 | no | Provide more vehicle attributes or select catalogue IDs. | 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` | 422 | no | The vehicle is outside the supported valuation range. | Check the registration year (1900 to next year) and mileage (zero or more, with the correct unit). |
| `concurrency_limited` | 429 | yes | Too many valuations are running at the same time for this organization. | 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` | 429 | yes | The request rate limit was reached. Retry after the current minute. | Wait for the rate limit to reset, then retry the same request with its original idempotency key. |
| `test_limit_reached` | 429 | yes | This workspace has used its fair-use allowance of test-key requests for now. | 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. |
| `internal_error` | 500 | no | The valuation could not be completed. Contact support with the request ID. | Contact support with the request ID. Do not repeatedly retry unchanged input. |
| `engine_invalid_response` | 502 | yes | The valuation service returned an invalid response. | 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` | 502 | yes | The image service returned an invalid response. | 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` | 502 | yes | Vehicle interpretation returned an invalid response. | 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. |
| `engine_busy` | 503 | yes | The valuation engine is at capacity. Retry after a short delay. | 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` | 503 | no | The valuation service for this market is not configured correctly. | 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` | 503 | yes | The valuation engine is temporarily unavailable. After a confirmed failed response, use a new idempotency key for a fresh attempt. | 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` | 503 | yes | The image service is temporarily unavailable. | 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` | 503 | yes | The vehicle lookup service is temporarily unavailable. | 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` | 503 | yes | Market figures are temporarily unavailable. | Retry later after the service recovers. The failed request did not consume a credit. |
| `rate_limit_unavailable` | 503 | yes | Request limiting is temporarily unavailable. Retry later. | Retry after the indicated delay with the same idempotency key. The request was not started and no credit was used. |
| `resolution_unavailable` | 503 | yes | Vehicle interpretation is temporarily unavailable. | 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` | 503 | yes | The selling-time forecast is temporarily unavailable. | 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. |
| `engine_timeout` | 504 | yes | The valuation service did not respond within its time budget. | 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` | 504 | yes | Image retrieval did not finish within its time budget. | 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` | 504 | yes | The vehicle lookup service did not respond within its time budget. | 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` | 504 | yes | The valuation request exhausted its processing time budget. | 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` | 504 | yes | Vehicle interpretation did not finish within its time budget. | 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` | 504 | yes | The selling-time forecast did not finish within its time budget. | 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. |

Full reference: https://data-services.autouncle.com/docs/errors