The Price2Spy RESTAPI gives your systems read and write access to your Price2Spy account: products, the competitor URLs tracked for them, sites, measurements and pricing data. This guide is for the developers who build that integration.
| Item | Value |
|---|---|
| Base path | /api/v1 |
| Base URL | https://<api-host>/api/v1 — your Price2Spy contact supplies the host |
| Format | JSON in and out, Content-Type: application/json on every request with a body |
| Authentication | HMAC-SHA256 signature on every request (next section) |
| Credentials | A client ID and a client secret, issued per account by Price2Spy |
| Interactive reference | Swagger UI at /api/v1/swagger-ui/index.html where enabled — it describes the API but cannot call it, because it cannot sign requests |
Your credentials identify your account. Every request reads and writes that account’s data only, and no endpoint takes an account ID.
| Field | Value | Notes |
|---|---|---|
| METHOD | GET , POST , PATCH , DELETE | Uppercase |
| HOST | api.example.com:443 | The host you call, with or without its port. Both forms are accepted |
| CONTENT-TYPE | The Content-Type header exactly as sent, e.g. application/json | Only on POST, PATCH and DELETE, and only when you send a Content-Type header: sign it exactly as sent (if you send application/json; charset=UTF-8 , sign that whole string). With no header, as is usual on a DELETE or POST /automatch/{id}/promote , leave out the value and its newline, as on a GET |
| RESOURCE | /api/v1/products? page=1&size=20 | Path including /api/v1 , then ? and the query string if there is one. Percent-encoded exactly as it goes on the wire |
| DATE | 1791878400 | The same string you send in X-P2S-Date |
| BODY | The raw request body | The exact bytes sent. Empty on a GET , so the string ends with the newline after DATE |
GET
api.example.com:443
/api/v1/products?page=1&size=20
1791878400| Request | Body | Expected signature |
|---|---|---|
| GET /api/v1/products?page=1&size=20 | none | B/o+cDZ1wt7CE/u/Ub3WJu/UeWn7YRQOgmv9klR1FUI = |
| POST /api/v1/product | {“productName”:”Blue kettle”,”sku”:”KET001″} | b5KtT1gYjSqlkwZlildOEzS4Tmocqci/Kb8ny8x2w5M = |
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class Price2SpyClient {
private static final String HOST = "api.example.com";
private static final String CLIENT_ID = "your-client-id";
private static final String CLIENT_SECRET = "your-client-secret";
private final HttpClient http = HttpClient.newHttpClient();
public HttpResponse send(String method, String resource, String
json) throws Exception {
String date = String.valueOf(Instant.now().getEpochSecond());
byte[] body = json == null ? new byte[0] :
json.getBytes(StandardCharsets.UTF_8);
boolean write = !method.equals("GET");
StringBuilder toSign = new StringBuilder()
.append(method).append('\n')
.append(HOST).append('\n');
if (write) toSign.append("application/json").append('\n');
toSign.append(resource).append('\n').append(date).append('\n');
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new
SecretKeySpec(CLIENT_SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
mac.update(toSign.toString().getBytes(StandardCharsets.UTF_8));
mac.update(body);
String signature = Base64.getEncoder().encodeToString(mac.doFinal());
HttpRequest.Builder request =
HttpRequest.newBuilder(URI.create("https://" + HOST + resource))
.header("Authorization", "HmacSHA256 " + CLIENT_ID + ":" +
signature)
.header("X-P2S-Date", date)
.method(method, body.length == 0 ? BodyPublishers.noBody() :
BodyPublishers.ofByteArray(body));
if (write) request.header("Content-Type", "application/json");
return http.send(request.build(),
HttpResponse.BodyHandlers.ofString());
}
} using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
public class Price2SpyClient
{
private const string Host = "api.example.com";
private const string ClientId = "your-client-id";
private const string ClientSecret = "your-client-secret";
private readonly HttpClient _http = new();
public async Task SendAsync(HttpMethod method,
string resource, string? json = null)
{
var date = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var body = json is null ? Array.Empty() :
Encoding.UTF8.GetBytes(json);
var write = method != HttpMethod.Get;
var toSign = new StringBuilder()
.Append(method.Method).Append('\n')
.Append(Host).Append('\n');
if (write) toSign.Append("application/json").Append('\n');
toSign.Append(resource).Append('\n').Append(date).Append('\n');
var head = Encoding.UTF8.GetBytes(toSign.ToString());
var message = new byte[head.Length + body.Length];
head.CopyTo(message, 0);
body.CopyTo(message, head.Length);
using var hmac = new
HMACSHA256(Encoding.UTF8.GetBytes(ClientSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(message));
var request = new HttpRequestMessage(method, $"https://{Host}
{resource}");
request.Headers.TryAddWithoutValidation("Authorization", $"HmacSHA256
{ClientId}:{signature}");
request.Headers.Add("X-P2S-Date", date);
if (write)
{
request.Content = new ByteArrayContent(body);
request.Content.Headers.ContentType = new
MediaTypeHeaderValue("application/json");
}
return await _http.SendAsync(request);
}
} import base64, hashlib, hmac, json, time
import requests
HOST = "api.example.com"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
def send(method, resource, body=None):
date = str(int(time.time()))
payload = b"" if body is None else json.dumps(body, separators=(",",
":")).encode("utf-8")
write = method != "GET"
fields = [method, HOST] + (["application/json"] if write else []) +
[resource, date]
to_sign = ("\n".join(fields) + "\n").encode("utf-8") + payload
digest = hmac.new(CLIENT_SECRET.encode("utf-8"), to_sign,
hashlib.sha256).digest()
signature = base64.b64encode(digest).decode("ascii")
headers = {"Authorization": f"HmacSHA256 {CLIENT_ID}:{signature}", "XP2S-Date": date}
if write:
headers["Content-Type"] = "application/json"
return requests.request(method, f"https://{HOST}{resource}",
headers=headers, data=payload)import base64, hashlib, hmac, json, time
import requests
HOST = "api.example.com"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
def send(method, resource, body=None):
date = str(int(time.time()))
payload = b"" if body is None else json.dumps(body, separators=(",",
":")).encode("utf-8")
write = method != "GET"
fields = [method, HOST] + (["application/json"] if write else []) +
[resource, date]
to_sign = ("\n".join(fields) + "\n").encode("utf-8") + payload
digest = hmac.new(CLIENT_SECRET.encode("utf-8"), to_sign,
hashlib.sha256).digest()
signature = base64.b64encode(digest).decode("ascii")
headers = {"Authorization": f"HmacSHA256 {CLIENT_ID}:{signature}", "XP2S-Date": date}
if write:
headers["Content-Type"] = "application/json"
return requests.request(method, f"https://{HOST}{resource}",
headers=headers, data=payload)These rules apply to every endpoint. The endpoint reference only lists exceptions to them.
| Parameter | Default | Allowed |
|---|---|---|
| page | 1 | 1 or more |
| size | 20 |
|
{
"items": [ ... ],
"page": 1,
"size": 20,
"total": 137,
"totalPages": 7
}
| Verb | Used for | Success | Body returned |
|---|---|---|---|
| POST to a collection, e.g. /products | Create | 201 Created | The created record |
| POST to a record action, e.g. /automatch/{id}/promote | An action | 200 OK | Depends on the action |
| PATCH | Update | 200 OK | The updated record |
| DELETE | Delete | 204 No Content | None |
| You send | Meaning |
|---|---|
| Field left out | Keep the current value |
| “field”: “new value” | Set it |
| “field”: null |
|
| You send | Meaning |
|---|---|
| 2026-08-01T12:00:00Z | That instant, UTC |
| 2026-08-01T14:00:00+02:00 | That instant, at the given offset |
| 2026-08-01T14:00:00 | That time in server time (Central European Time, as in Paris: UTC+1 in winter, UTC+2 in summer) |
| 2026-08-01 | The whole day: from 00:00:00 on a …From filter, to 23:59:59 on a …To filter |
Every failure returns one JSON shape, whatever the status: statusCode and message, plus fieldErrors when a value failed validation, or errorId on a server error.
{
"statusCode": 400,
"message": "Bad request",
"fieldErrors": [
{ "field": "size", "message": "Page size cannot exceed 500" },
{ "field": "page", "message": "Invalid value, but got: abc" }
]
}{
"statusCode": 500,
"message": "An unexpected error occurred",
"errorId": ""
} | Status | When | What to do |
|---|---|---|
| 400 Bad Request | A query or body value failed validation ( fieldErrors names each field); the body is not valid JSON; the Authorization header is present but malformed; X-P2S-Date is missing, not a number, or more than 900 seconds from server time; a business rule refused the request ( message says which) | Fix the request. For the date header, check your clock |
| 401 Unauthorized | No Authorization header or a scheme other than HmacSHA256 ; unknown client ID; signature does not match; API access is not enabled for the account | See Troubleshooting. The message is deliberately brief |
| 403 Forbidden | The record cannot be changed, e.g. a product that is not editable | Do not retry |
| 404 Not Found | The record does not exist in your account, or the path does not exist. A list that matches nothing is a 200 with no items, not a 404 | Check the ID and the path |
| 405 Method Not Allowed | The path exists but not with this verb. The Allow header lists the verbs it takes | Use a listed verb |
| 409 Conflict | The change conflicts with existing data, e.g. a name already in use | Change the value |
| 415 Unsupported Media Type | A body was sent without Content-Type: application/json | Send that header |
| 429 Too Many Requests | You exceeded your rate limit (below) | Wait at least one second, then retry |
| 500 Internal Server Error | An unexpected failure on our side | Retry later. If it persists, send us the errorId |
{
"statusCode": 429,
"message": "Exceeded the rate limit of 4 requests/second. Reduce the
request rate to resume uninterrupted service."
}The endpoints are in the Endpoints tab: a summary of all 43, then one sub-tab per section, in the same order as Swagger UI.
Most integration problems are signing problems, and the error message tells you which kind.
| You get | LIkely cause | Fix |
|---|---|---|
| 401 “Hmac signature mismatch” | The string you signed differs from the request you sent | Work through the checklist below |
| 401 “Hmac auth header missing” | No Authorization header, or it does not start with exactly HmacSHA256 (case matters) | Send HmacSHA256 <clientId>:<signature> |
| 400 “Authorization header with HmacSHA256 scheme not provided” | The header does not match HmacSHA256 <clientId>: <signature> , e.g. extra spaces or a missing colon | One space after the scheme, none elsewhere |
| 400 “HMAC timestamp expired” | X-P2S-Date is more than 900 seconds from server time, often because milliseconds were sent instead of seconds | Send whole seconds and keep the clock synced (NTP) |
| 400 “Hmac missing timestamp header” or “Hmac invalid timestamp header” | X-P2S-Date is absent or not a whole number | Send Unix seconds, e.g. 1791878400 |
| 401 “API access denied for client ID …” | API access is not enabled for your account | Contact Price2Spy |
| 401 “Authentication failed” or “Invalid client ID” | The client ID is not recognised | Check the client ID you were issued |
| A date filter returns less than you expected | A date without an offset is read as server time (Central European Time), not UTC | Add Z or an offset |
| A field you sent did not change | The field name is misspelled, so it was ignored | Compare with the reference; the response shows what was stored |
| 429 under load | Parallel workers share one client ID’s per-second limit | Throttle across all workers together |
Check these in order. They are listed by how often they cause the problem.
If you are still stuck, send your Price2Spy contact the method, the full URL as sent, and the X-P2S-Date value from a failing request. Never send your client secret.
| Section | Method and path | Purpose | Success |
|---|---|---|---|
| Products | GET /products | Search products | 200, paged |
| POST /products | Create a product | 201 | |
| PATCH /products | Update a product | 200 | |
| DELETE /products/{id} | Delete a product and its URLs | 204 | |
| URLs | GET /urls | Search competitor URLs | 200, paged |
| POST /urls | Add a URL to a product | 201 | |
| PATCH /urls | Update a URL | 200 | |
| DELETE /urls/{id} | Delete a URL | 204 | |
| Sites | GET /sites | List sites your URLs are on | 200, paged |
| PATCH /sites | Set a site’s custom name, priority or alert setting | 200 | |
| Measurements | GET /measurements | Price checks for one URL | 200, paged |
| Pricing data | GET /pricing-data/last-price-change | URLs whose latest price changed | 200, paged |
| GET /pricing-data/product-pricehistory/{id} | All price checks for one product | 200, paged | |
| GET /pricing-data/current-pricingdata | Products with their URLs and current prices | 200, paged (max 50) | |
| Price buckets | GET /price-buckets | Price ranges and product counts | 200, paged |
| Metadata | GET, POST, PATCH and DELETE …/{id} on /brands, /categories, /suppliers, /metadata/{one|two|three} | Manage brands, categories, suppliers and your three custom lists | 200 / 201 / 200 / 204 |
| Automatch | GET /automatch | List automatch suggestions | 200, paged |
| POST /automatch/{automatchUrlId}/promote | Accept a suggestion as a URL | 200 | |
| POST /automatch/{urlId}/demote | Turn a promoted URL back into a rejected suggestion | 200 | |
| POST /automatch/{automatchUrlId}/reject | Reject a suggestion | 200 |
Searches your products, ordered by product ID. All filters are optional and combine with AND.
| Parameter | Type | Matches |
|---|---|---|
| productId | integer | That product |
| productName, sku, internalId | text | Per searchMode |
| url | text, 3+ characters | Products with a URL matching this text, per searchMode |
| categoryId, brandId, supplierId, metadata1Id, metadata2Id, metadata3Id | integer | That linked record |
| metadataFilter.categoryName, .brandName, .supplierName, .metadata1Name, .metadata2Name, .metadata3Name | text | The linked record’s name, per searchMode |
| customFieldFilter.customField1 … customField10 | text | Per searchMode |
| comment1, comment2 | text | Per searchMode |
| dateChangeFrom, dateChangeTo | date | Products with at least one URL whose latest price check falls in the range. Combined with url, the same URL must match both |
| active | boolean | Active or inactive products |
| frequencyType/span> + frequencyInterval | DAYS/HOURS + integer (max 60) | Products checked at exactly that frequency. Send both or neither |
| searchMode | LIKE (default) or EQUAL | LIKE matches text anywhere in the value; EQUAL matches the whole value. Applies to every text filter in the request |
Product fields, in response order:
| Field | Type | Notes |
|---|---|---|
| productId | integer | |
| productName | text | Unique within your account |
| checkFrequencyType, checkFrequencyInterval | DAYS / HOURS, integer | How often the product’s URLs are checked. A whole number of days is always shown as DAYS |
| active, showInReports, repricingExcluded | boolean | |
| sku, internalId | text | |
| categoryName, categoryId, brandName, brandId, supplierName, supplierId | text, integer | |
| minPrice, maxPrice | price object | Lowest and highest current price across the product’s active URLs: {“currency”: “EUR”, “amount”: 12.30}. Converted, see Currency in the Guide. |
| lastChecked, nextCheck, lastChanged | date | Last time a URL was checked, next scheduled check, time of the most recent stored measurement |
| urlCount | integer | |
| targetPrice, costPrice … ceilingPrice, bottomPrice | decimal | |
| metadata1Name, metadata1Id … metadata3Name, metadata3Id | text, integer | Your three custom lists |
| customField1 … customField10, comment1, comment2 | text | |
| dateAdded, dateModified, addedById, modifiedById | date, integer |
{
"productName": "Blue kettle 1.7 l",
"sku": "KET-001",
"checkFrequencyType": "DAYS",
"checkFrequencyInterval": 1,
"brandName": "Acme",
"costPrice": 18.50,
"targetPrice": 29.99
}| Field | Required | Rules |
|---|---|---|
| productName | yes | Up to 250 characters, unique in your account |
| checkFrequencyType, checkFrequencyInterval | no | Send both. If either is missing, your plan’s default is used. Allowed values below |
| active | no | Default true |
| repricingExcluded | no | Default false |
| sku, internalId | no | Up to 250 characters |
| targetPrice, costPrice, ceilingPrice, bottomPrice | no | 0 to 9,999,999,999.99 |
| categoryName, brandName, supplierName, metadata1Name, metadata2Name, metadata3Name | no | Up to 250 characters. A name that does not exist yet is created |
| customField1 … customField10 | no | Up to 250 characters |
| comment1, comment2 | no |
Check frequency allowed by plan
| Plan | Allowed | Default |
|---|---|---|
| Weekly checking | 7, 14, 30 or 60 days | 7 days |
| All other plans | 1, 2, 3, 5, 7, 14 or 30 days; also 3, 4, 6, 8 or 12 hours on premium accounts | 1 day |
Errors: 404 product not found; 403 the product is not editable; 409 name already used,
or activating the product would exceed your plan’s limit; 400 frequency not allowed
A URL is one competitor page tracked for a product. Each URL belongs to a site, which the API works out from the address.
Searches your URLs, ordered by product ID, then URL ID. Text filters match anywhere in the value.
| Parameter | Type | Matches |
|---|---|---|
| id | integer | That URL |
| productId | integer | URLs of that product |
| productName, sku, internalId | text | The owning product |
| query | text, 3+ characters | Product name, SKU or internal ID. When used, the four filters above it are ignored. Under 3 characters, query itself is ignored |
| active | boolean | Active or inactive URLs |
URL fields, in response order:
| Field | Type | Notes |
|---|---|---|
| urlId, productId | integer | |
| url | text | |
| productName | text | The name stored for this URL, which may differ from the product’s name |
| siteHumanName, siteCountryISOCode | text | The site’s name and country. Your own name for the site (see Sites) and your account’s country for it take precedence |
| showInReports, active | boolean | |
| deactivatedBy, deactivationDate | integer, date | Who deactivated the URL and when |
| multiplicator | decimal | Multiplier applied to the price found on the page. Default 1 |
| note1 … note3, image1Url … image3Url | text | |
| counterFailed, lastError | integer, text | Consecutive failed checks and the last error |
| lastChecked | date | |
| lastMeasurement, secondToLastMeasurement | measurement | See Measurements . price is converted, see Currency in the Guide |
| automatchUrl | automatch | Present when the URL came from an automatch suggestion. See Automatch |
| dateAdded, dateModified, addedById, modifiedById | date, integer |
Adds a URL to a product. If the site is new to Price2Spy, it is created.
| Field | Required | Rules |
|---|---|---|
| productId | yes | A product in your account |
| url | yes | A valid URL, up to 2,000 characters |
| active | no | Default true |
| showInReports | no | Default true |
| note1, note2, note3 | no | |
| multiplicator | no | Greater than 0, up to 4 decimal places and 8 digits before the point. Only on sites where multipliers are enabled |
| Field | Rules |
|---|---|
| url | Must stay on the same site. To move to another site, delete the URL and add a new one. Cannot be cleared |
| active | Setting false records the deactivation date. null keeps |
| showInReports | null keeps |
| note1, note2, note3 | null clears |
| multiplicator | As on create. Send 1 to reset; null keeps |
| counterFailed | 0 or more. Send 0 to reset the failure counter |
A site is a web shop. You see only the sites where your account has at least one URL.
Lists your sites: those with a priority first (lowest number first), then by name.
| Parameter | Type | Matches |
|---|---|---|
| searchTerm | text | Custom name or site name, anywhere in the value |
| id | integer | That site |
| customName, siteName, homeUrl | text | Anywhere in the value |
| countryCode | text | Exact ISO country code |
| priority | integer | Exact. 0 means no priority |
| hasAccountSpecific, ignoreEmailAlerts | boolean |
| Parameter | Type | Notes |
|---|---|---|
| id | integer | |
| name | text | The site’s name in Price2Spy |
| customName | text | Your own name for the site |
| homeUrl, countryCode | text | |
| priority | integer | 0 if not set |
| hasAccountSpecific | boolean | Your account has its own settings for this site |
| ignoreEmailAlerts | boolean | The site is left out of your email alerts |
| priceRule | object or null | {“field”, “operation”, “value”} — your price rule for the site |
| Field | Rules |
|---|---|
| customName | Up to 100 characters, null clears |
| priority | Integer. null keeps |
| ignoreEmailAlerts | Boolean. null keeps |
A measurement is one price check of one URL
Returns the price checks for one URL, newest first.
| Parameter | Type | Notes |
|---|---|---|
| urlId | integer | required |
| dateCheckedFrom, dateCheckedTo | date | Optional. No range limit |
Errors: 404 URL not found.
Measurement fields, in response order:
| Field | Type | Notes |
|---|---|---|
| urlId, url, siteHumanName | integer, text | Only in product price history, where rows come from several URLs |
| dateChecked | date | |
| price | price object | {“currency”: “EUR”, “amount”:12.30}. Converted, see Currency in the Guide |
| available | boolean | Always present |
| shippingCost, shelfPrice | decimal | As found on the site, not converted |
| shippingTime, shippingDetails, stockStatus, seller, promotionText | text | |
| isOnPromotion | boolean | |
| customField1 … customField10 | text | |
| screenshotUrl | text | Link to the screenshot taken during the check |
When you leave dates out
| You send | last-price-change | product-price-history | current-pricing-data |
|---|---|---|---|
| No dates | Last 30 days | Last year | All current data, no date filter |
| Start only | Start to now (at most one year) | Start to now (at most one year) | From the start |
| End only | One year before the end to the end, but no earlier than one year ago | Same | Up to the end |
| Both | As sent | As sent | As sent |
Returns one row per URL whose latest price differs from the price before it, newest change first. A price appearing or disappearing counts as a change; a URL checked only once does not appear. The date range applies to the latest check.
| Parameter | Type | Notes |
|---|---|---|
| type | INCREASE or DECREASE | Optional. Without it, every change is listed, including a price appearing or disappearing; with it, only rows where both prices exist |
| latestChangeDateFrom, latestChangeDateTo | date | See the table above |
| Group | Fields |
|---|---|
| The URL | dateChanged (time of the latest check), productId, productName, siteName, urlId, url |
| Latest check | latestPrice, latestCurrency, LatestAvailability, latestOnPromotion, latestShippingCost, latestShippingTime, latestShippingDetails, latestStockStatus, latestSeller, latestShelfPrice, latestPromotionText, latestCustomField1 … latestCustomField10 |
| Check before it | previousDateChanged, then the same fields with the previous prefix |
| Your own site | myOwnPrice, myOwnCurrency, myOwnAvailability — the latest check of this product on your own shop, when there is one |
| Parameter | Type | Notes |
|---|---|---|
| dateCheckedFrom, dateCheckedTo | date | See the table above |
| Field | Type | Notes |
|---|---|---|
| id, accountId | integer | |
| name | text | |
| priceFrom, priceTo | decimal | priceTo is null for an open-ended range |
| numberOfProducts | integer |
Automatch suggestions are competitor pages Price2Spy found that may match your products. You can promote a suggestion into a tracked URL, or reject it.
| List | Path | Product field |
|---|---|---|
| Brands | /brands | brandName |
| Categories | /categories | categoryName |
| Suppliers | /suppliers | supplierName |
| Account metadata 1, 2, 3 | /metadata/one, /metadata/two, /metadata/three | metadata1Name , metadata2Name , metadata3Name |
Creates an entry.
| Field | Required | Rules |
|---|---|---|
| name | yes | Up to 250 characters, unique within that list |
| active | no | Default true |
| priority | no | Integer. Default 0 |
| emailRecipient | no | Valid addresses, each up to 100 characters; together up to 500 characters including one separator between each pair |
Automatch suggestions are competitor pages Price2Spy found that may match your products. You can promote a suggestion into a tracked URL, or reject it.
| Status | Meaning | approved in the response |
|---|---|---|
| UNPROCESSED | Not decided yet | absent |
| APPROVED | Promoted to a URL | true |
| REJECTED | Rejected, or demoted after promotion | false |
Lists suggestions. The order is not fixed, so do not rely on the position of a row across pages.
| Parameter | Type | Matches |
|---|---|---|
| id | integer | That suggestion |
| productId | integer | Suggestions for that product |
| name, sku, internalId | text | The product’s value, exactly |
| status | APPROVED , REJECTED , UNPROCESSED | |
| dateAutomatchFrom, dateAutomatchTo | date | When the suggestion was found |
Rejects an unprocessed suggestion. No body; returns 200 with no body. Errors: 404 not found; 409 already promoted or already processed.