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_01JBX4Q8ZJ7M2K"
}

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).

HTTP status codes#

Status	Meaning	What to do
`200`, `201`, `204`	It worked	Read the body, if there is one
`304`	Nothing changed since your `ETag`	Use your cached copy
`400`	The request is malformed	Fix the request; check `code` and `errors`
`401`	No key, or a key that doesn't work	Check the `Authorization` header and the key
`403`	The key can't do this	Use a key with the right scope
`404`	Not found for your company	Check the id or SKU
`405`	Wrong HTTP method	See the `Allow` header
`412`	A precondition failed	Read the resource again, then decide
`413`	The body is over 1 MB, whether or not you sent `Content-Length`	Send less
`415`	The body isn't JSON	Send `Content-Type: application/json`
`422`	The JSON body is invalid	Fix the field named in `errors`
`429`	Too many requests	Wait `Retry-After` seconds
`500`	Something failed on our side	Don't retry; contact support with the `request_id`
`503`	Temporarily unavailable	Wait `Retry-After` seconds, then retry

A 401 carries a WWW-Authenticate: Bearer realm="api.getprice.ai" header.

Error codes#

Code	Status	Meaning	How to fix
`validation_failed`	400	A parameter value is invalid, such as more than 100 `sku` values or `limit=0`	Fix the value named in `errors`. Don't retry.
`unknown_parameter`	400	The endpoint doesn't take this query parameter, often because of a typo	Fix the parameter name. Don't retry.
`invalid_parameter`	400	A parameter value contains a control character	Remove the character. Don't retry.
`cursor_mismatch`	400	The filters or the endpoint changed while you paged with a cursor	Start again without a cursor. Don't retry.
`invalid_cursor`	400	The cursor is malformed, altered or expired	Start again without a cursor. Don't retry.
`unauthenticated`	401	There's no `Authorization: Bearer` header	Send your key. Don't retry.
`invalid_key`	401	The key is malformed, 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_scope`	403	The key lacks this endpoint's scope	Use a key with that scope. Don't retry.
`not_found`	404	There's no such resource for your company	Check the id or SKU. Don't retry.
`product_not_found`	404	`product_id` isn't one of your own products	Use an id from `GET /v1/products`. Don't retry.
`method_not_allowed`	405	The path doesn't support this HTTP method	Use a method from the `Allow` header. Don't retry.
`precondition_failed`	412	You sent `If-None-Match: *` and the SKU is already linked, or `If-Match` didn't match	Read the link again, then decide. Don't retry.
`payload_too_large`	413	The request body is over 1 MB, whether or not you sent `Content-Length`	Send a smaller body. Don't retry.
`unsupported_media_type`	415	The body isn't `application/json`	Set `Content-Type: application/json`. Don't retry.
`validation_failed`	422	The JSON body is invalid, such as a missing `product_id`	Fix the field named in `errors`. Don't retry.
`rate_limited`	429	This request costs more units than you have left this minute	Wait `Retry-After` seconds, then retry
`internal_error`	500	Something failed on our side	Contact support with the `request_id`. Don't retry.
`unavailable`	503	GetPrice can't guarantee correct match data right now, or is too busy	Wait `Retry-After` seconds, then retry

Reserved codes#

The API doesn't send these yet: key_revoked, plan_required, conflict, cursor_expired, idempotency_key_reused, precondition_required, concurrency_limited and quota_exceeded. 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.