Skip to content

Concepts

Errors

Errors use the standard problem details format (RFC 9457), with content type application/problem+json:

JSON
{
  "type": "https://api.getprice.ai/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No mapping for this SKU.",
  "code": "not_found",
  "request_id": "req_7f3c2a91d4e84b0c9a6e15b2c8d40f37"
}

Branch on code, never on title or detail: those are for people, and their wording may change. Within v1, a code is never renamed or removed; new ones may be added. Validation errors add an errors list that names each bad parameter (query string) or pointer (JSON body field).

type identifies the error: https://api.getprice.ai/errors/ plus the code with hyphens. Opening it takes you to that code's row in the table below.

HTTP status codes#

StatusMeaningWhat to do
200, 201, 204It workedRead the body, if there is one
304Nothing changed since your ETagUse your cached copy
400The request is malformedFix the request; check code and errors
401No key, or a key that doesn't workCheck the Authorization header and the key
403The key can't do thisUse a key with the right scope
404Not found for your companyCheck the id or SKU
405Wrong HTTP methodSee the Allow header
409The change clashes with your dataCheck code, then decide
412A precondition failedRead the resource again, then decide
413The body is over 1 MB, whether or not you sent Content-LengthSend less
415The body isn't JSONSend Content-Type: application/json
422The JSON body is invalidFix the field named in errors
429Too many requestsWait Retry-After seconds
500Something failed on our sideDon't retry; contact support with the request_id
503Temporarily unavailableWait Retry-After seconds, then retry

A 401 carries a WWW-Authenticate: Bearer realm="api.getprice.ai" header, with error="invalid_token" once a key was sent. A 403 carries the same header with error="insufficient_scope" and the missing scope.

Error codes#

CodeStatusMeaningHow to fix
validation_failed400A parameter value is invalid, such as more than 100 sku values or limit=0Fix the value named in errors. Don't retry.
unknown_parameter400The endpoint doesn't take this query parameter, often because of a typoFix the parameter name. Don't retry.
invalid_parameter400A parameter value contains a control characterRemove the character. Don't retry.
cursor_mismatch400The filters or the endpoint changed while you paged with a cursorStart again without a cursor. Don't retry.
invalid_cursor400The cursor is malformed, altered or expiredStart again without a cursor. Don't retry.
unauthenticated401There's no Authorization: Bearer headerSend your key. Don't retry.
invalid_key401detail says The API key is malformed. (format or checksum) or The API key is not valid. (unknown, revoked or expired; we don't say which)Check for copy-paste damage. If the key is intact, an admin can regenerate it in Settings. Don't retry.
insufficient_scope403The key lacks this endpoint's scopeUse a key with that scope. Don't retry.
not_found404There's no such resource for your companyCheck the id or SKU. Don't retry.
product_not_found404product_id isn't one of your own productsUse an id from GET /v1/products. Don't retry.
method_not_allowed405The path doesn't support this HTTP methodUse a method from the Allow header. Don't retry.
sku_on_website409The SKU is on one of your website products, and you tried to link it to a product built from your catalogue. The body's product_id is the website productKeep the SKU on the website product, or link another SKU. Don't retry.
conflict409A write clashed with another changeRead the resource again, then decide. Don't retry.
precondition_failed412You sent If-None-Match: * and the SKU is already linked, or If-Match didn't matchRead the link again, then decide. Don't retry.
payload_too_large413The request body is over 1 MB, whether or not you sent Content-LengthSend a smaller body. Don't retry.
unsupported_media_type415The body isn't application/jsonSet Content-Type: application/json. Don't retry.
validation_failed422The JSON body is invalid, such as a missing product_idFix the field named in errors. Don't retry.
rate_limited429This request costs more units than you have left this minuteWait Retry-After seconds, then retry
internal_error500Something failed on our sideContact support with the request_id. Don't retry.
unavailable503GetPrice can't guarantee correct match data right now, or is too busyWait Retry-After seconds, then retry

Codes you don't recognise#

New codes may be added within v1. Handle any code you don't recognise by its HTTP status: retry 429 and 503 after Retry-After, and 502 and 504 with backoff. Never retry a 500 without changing something.

These codes are reserved in the API's list but not sent today:

CodeReserved for
key_revokedA revoked key, if it is ever told apart from an unknown one
plan_requiredA feature your plan doesn't include
cursor_expiredA cursor too old to use
precondition_requiredA write that must send If-Match
idempotency_key_reusedAn idempotency key reused with a different request
concurrency_limitedToo many requests at the same time
quota_exceededA monthly or daily quota