Problems
Every error either API answers with: an RFC 9457 problem, the statuses it comes with and when.
The problem
An error of either API. Its type is always about:blank, so the status tells problems apart.
A URI naming the kind of problem.
The status's own phrase, such as Bad Request.
The answer's HTTP status.
detailstring
What happened and what to do next, for the person who can fix it.
violationsarray of objects
For invalid input, every value that is wrong.
One thing that is wrong with the input, and where.
DraftConflict
A write to a draft that was refused with 409: a problem, and where the draft stands.
SynonymsRefused
A write of synonyms that wrote nothing: a problem, and where every entry clashes, each entry with why.
The entries refused for their clashes; left out where the problem is another, such as a file that cannot be read.
400
| Endpoint | When |
|---|---|
POST /v1/search | The request cannot be answered as sent. |
GET /v1/search | The request cannot be answered as sent. |
GET /v1/product | The request names no product, or both an id and a URL, or a channel or locale the release lacks. |
GET /v1/resolve | The request names a channel or locale the release lacks. |
POST /v1/events | The body is not a batch of events: no events or more than events_per_call, an event naming both or neither of an entity and a placement, a position no page reaches, or a query ID that is not a UUIDv7 or names a time still to come. Nothing of it is taken. |
GET /api/v1/rules | The channel, locale or time cannot be answered, such as a channel the release lacks. |
GET /api/v1/imports/{import}/rules | The channel, locale or time cannot be answered, such as a channel the release lacks. |
POST /api/v1/imports/{import}/synonyms/check | The body names a channel or locale the release lacks. |
GET /api/v1/search-settings | The locale is not one the release serves. |
GET /api/v1/imports/{import}/search-settings | The locale is not one the release serves. |
POST /api/v1/pages/settings | The body names a category the live catalog lacks, or a channel or locale the release lacks. |
POST /api/v1/preview/search | The request cannot be answered as sent, such as a channel or context key the release lacks. |
POST /api/v1/preview/page | The request cannot be answered as sent, such as a channel or context key the release lacks. |
POST /api/v1/preview/compare | The body is not a trace and two places. |
POST /api/v1/preview/find | The request cannot be answered as sent, or the body names no entity. |
401
| Endpoint | When |
|---|---|
PUT /api/v1/catalog | The management key is missing or wrong. |
GET /api/v1/catalog-source | The management key is missing or wrong. |
PUT /api/v1/catalog-source | The management key is missing or wrong. |
DELETE /api/v1/catalog-source | The management key is missing or wrong. |
POST /api/v1/catalog-source/fetch | The management key is missing or wrong. |
GET /api/v1/imports | The management key is missing or wrong. |
POST /api/v1/imports | The management key is missing or wrong. |
GET /api/v1/imports/{import} | The management key is missing or wrong. |
PATCH /api/v1/imports/{import} | The management key is missing or wrong. |
DELETE /api/v1/imports/{import} | The management key is missing or wrong. |
GET /api/v1/imports/{import}/inspection | The management key is missing or wrong. |
GET /api/v1/imports/{import}/suggestions | The management key is missing or wrong. |
GET /api/v1/imports/{import}/changes | The management key is missing or wrong. |
POST /api/v1/imports/{import}/publish | The management key is missing or wrong. |
GET /api/v1/imports/{import}/publication | The management key is missing or wrong. |
GET /api/v1/rules | The management key is missing or wrong. |
GET /api/v1/imports/{import}/rules | The management key is missing or wrong. |
POST /api/v1/imports/{import}/rules | The management key is missing or wrong. |
PATCH /api/v1/imports/{import}/rules/{rule} | The management key is missing or wrong. |
DELETE /api/v1/imports/{import}/rules/{rule} | The management key is missing or wrong. |
PUT /api/v1/imports/{import}/rules/{rule}/position | The management key is missing or wrong. |
GET /api/v1/synonyms | The management key is missing or wrong. |
GET /api/v1/imports/{import}/synonyms | The management key is missing or wrong. |
POST /api/v1/imports/{import}/synonyms | The management key is missing or wrong. |
PATCH /api/v1/imports/{import}/synonyms/{synonym} | The management key is missing or wrong. |
DELETE /api/v1/imports/{import}/synonyms/{synonym} | The management key is missing or wrong. |
POST /api/v1/imports/{import}/synonyms/check | The management key is missing or wrong. |
GET /api/v1/search-settings | The management key is missing or wrong. |
GET /api/v1/imports/{import}/search-settings | The management key is missing or wrong. |
PATCH /api/v1/imports/{import}/search-settings/{type} | The management key is missing or wrong. |
GET /api/v1/releases | The management key is missing or wrong. |
POST /api/v1/releases | The management key is missing or wrong. |
GET /api/v1/releases/{release} | The management key is missing or wrong. |
POST /api/v1/releases/{release}/publish | The management key is missing or wrong. |
GET /api/v1/releases/{release}/publication | The management key is missing or wrong. |
GET /api/v1/index-runs | The management key is missing or wrong. |
POST /api/v1/index-runs | The management key is missing or wrong. |
GET /api/v1/index-runs/{index_run} | The management key is missing or wrong. |
GET /api/v1/live | The management key is missing or wrong. |
PUT /api/v1/offers | The management key is missing or wrong. |
GET /api/v1/storage | The management key is missing or wrong. |
PATCH /api/v1/storage | The management key is missing or wrong. |
GET /api/v1/insights | The management key is missing or wrong. |
GET /api/v1/insights/campaigns | The management key is missing or wrong. |
GET /api/v1/categories | The management key is missing or wrong. |
POST /api/v1/pages/settings | The management key is missing or wrong. |
POST /api/v1/preview/search | The management key is missing or wrong. |
POST /api/v1/preview/page | The management key is missing or wrong. |
POST /api/v1/preview/compare | The management key is missing or wrong. |
POST /api/v1/preview/find | The management key is missing or wrong. |
404
409
| Endpoint | When |
|---|---|
PATCH /api/v1/imports/{import} | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
DELETE /api/v1/imports/{import} | The import was published. |
POST /api/v1/imports/{import}/publish | The draft changed since version was read, or while its release was built, and draft is the draft as it is now; or the import was discarded, is going live already, its export was removed, or it removes half the live products or more and removing does not name how many, and draft is left out. |
GET /api/v1/imports/{import}/publication | There is no catalog yet, so nothing can be indexed before one is uploaded. |
POST /api/v1/imports/{import}/rules | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
PATCH /api/v1/imports/{import}/rules/{rule} | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
DELETE /api/v1/imports/{import}/rules/{rule} | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
PUT /api/v1/imports/{import}/rules/{rule}/position | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
POST /api/v1/imports/{import}/synonyms | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
PATCH /api/v1/imports/{import}/synonyms/{synonym} | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
DELETE /api/v1/imports/{import}/synonyms/{synonym} | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
PATCH /api/v1/imports/{import}/search-settings/{type} | The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out. |
GET /api/v1/releases/{release}/publication | There is no catalog yet, so nothing can be indexed before one is uploaded. |
POST /api/v1/index-runs | There is no catalog or no published release yet. |
PUT /api/v1/offers | Nothing is live yet, so no product is known; send a catalog first. |
413
| Endpoint | When |
|---|---|
POST /v1/events | The body is larger than the 64 kB a beacon may carry. |
PUT /api/v1/catalog | The body is larger than the control plane accepts. |
POST /api/v1/imports | The body is larger than the control plane accepts. |
422
| Endpoint | When |
|---|---|
PUT /api/v1/catalog | The body holds no catalog. |
PUT /api/v1/catalog-source | A setting is missing or out of range. |
POST /api/v1/imports | The body holds no export. |
PATCH /api/v1/imports/{import} | The release the files make has violations. |
GET /api/v1/imports/{import}/inspection | The export cannot be read, or the release has violations. |
GET /api/v1/imports/{import}/suggestions | The export cannot be read, or the release has violations. |
GET /api/v1/imports/{import}/changes | An export cannot be read, or the release has violations. |
POST /api/v1/imports/{import}/publish | The release the files make has violations. |
GET /api/v1/imports/{import}/publication | The draft files make a release with violations; each names its file, a JSON pointer and what is wrong. |
GET /api/v1/imports/{import}/rules | The draft files make a release with violations; each names its file, a JSON pointer and what is wrong. |
POST /api/v1/imports/{import}/rules | The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here. |
PATCH /api/v1/imports/{import}/rules/{rule} | The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here. |
DELETE /api/v1/imports/{import}/rules/{rule} | The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here. |
PUT /api/v1/imports/{import}/rules/{rule}/position | The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here. |
GET /api/v1/imports/{import}/synonyms | The draft's synonyms.json cannot be read; change it through the draft's files. |
POST /api/v1/imports/{import}/synonyms | Nothing is written: every entry clashes, and refused says why for each; or the release the write makes has violations, each with a JSON pointer. |
PATCH /api/v1/imports/{import}/synonyms/{synonym} | Nothing is written: every entry clashes, and refused says why for each; or the release the write makes has violations, each with a JSON pointer. |
DELETE /api/v1/imports/{import}/synonyms/{synonym} | Nothing is written: every entry clashes, and refused says why for each; or the release the write makes has violations, each with a JSON pointer. |
POST /api/v1/imports/{import}/synonyms/check | The draft's synonyms.json cannot be read, or the entry has more than words_per_check words. |
GET /api/v1/imports/{import}/search-settings | The release the draft makes has violations; change it through the draft's files. |
PATCH /api/v1/imports/{import}/search-settings/{type} | The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here. |
POST /api/v1/releases | The release has violations. |
GET /api/v1/releases/{release}/publication | The draft files make a release with violations; each names its file, a JSON pointer and what is wrong. |
PUT /api/v1/offers | The body holds no list of offers, or more than offers_per_call. |
PATCH /api/v1/storage | The setting is out of range. |
GET /api/v1/insights | A day or the traffic is not one the report can count. |
GET /api/v1/insights/campaigns | A day or the traffic is not one the report can count. |
POST /api/v1/pages/settings | The draft files make a release with violations; each names its file, a JSON pointer and what is wrong. |
POST /api/v1/preview/page | The draft files make a release with violations; each names its file, a JSON pointer and what is wrong. |
POST /api/v1/preview/compare | The trace's rank step holds no hit of the section at one of the places. |
502
| Endpoint | When |
|---|---|
PATCH /api/v1/imports/{import} | The Query API could not check it. |
GET /api/v1/imports/{import}/inspection | The Query API could not inspect it. |
GET /api/v1/imports/{import}/suggestions | The Query API or the AI gateway did not answer. |
GET /api/v1/imports/{import}/changes | The Query API could not compare them. |
POST /api/v1/imports/{import}/publish | The Query API could not check it. |
GET /api/v1/imports/{import}/publication | The Query API could not be reached. |
GET /api/v1/rules | The Query API could not be reached. |
GET /api/v1/imports/{import}/rules | The Query API could not be reached. |
POST /api/v1/imports/{import}/rules | The Query API could not be reached. |
PATCH /api/v1/imports/{import}/rules/{rule} | The Query API could not be reached. |
DELETE /api/v1/imports/{import}/rules/{rule} | The Query API could not be reached. |
PUT /api/v1/imports/{import}/rules/{rule}/position | The Query API could not be reached. |
GET /api/v1/synonyms | The Query API could not be reached. |
GET /api/v1/imports/{import}/synonyms | The Query API could not be reached. |
POST /api/v1/imports/{import}/synonyms | The Query API could not be reached. |
PATCH /api/v1/imports/{import}/synonyms/{synonym} | The Query API could not be reached. |
DELETE /api/v1/imports/{import}/synonyms/{synonym} | The Query API could not be reached. |
POST /api/v1/imports/{import}/synonyms/check | The Query API could not be reached. |
GET /api/v1/search-settings | The Query API could not be reached. |
GET /api/v1/imports/{import}/search-settings | The Query API could not be reached. |
PATCH /api/v1/imports/{import}/search-settings/{type} | The Query API could not be reached. |
POST /api/v1/releases | The Query API could not check it. |
GET /api/v1/releases/{release}/publication | The Query API could not be reached. |
PUT /api/v1/offers | The Query API could not check them. |
GET /api/v1/categories | The Query API could not be reached. |
POST /api/v1/pages/settings | The Query API could not be reached. |
POST /api/v1/preview/search | The Query API could not be reached. |
POST /api/v1/preview/page | The Query API could not be reached. |
POST /api/v1/preview/compare | The Query API could not be reached. |
POST /api/v1/preview/find | The Query API could not be reached. |
503
| Endpoint | When |
|---|---|
POST /v1/search | Nothing is searchable yet, or the engine is unreachable. |
GET /v1/search | Nothing is searchable yet, or the engine is unreachable. |
GET /v1/product | Nothing is searchable yet, or the engine is unreachable. |
GET /v1/resolve | Nothing is searchable yet, or the engine is unreachable. |
GET /v1/robots | Nothing is searchable yet. |
GET /api/v1/imports/{import}/suggestions | Mapping suggestions are off: the Query API has no AI gateway key. |
GET /api/v1/rules | Nothing is searchable yet, or the engine is unreachable. |
GET /api/v1/imports/{import}/rules | Nothing is searchable yet, or the engine is unreachable. |
GET /api/v1/synonyms | Nothing is searchable yet. |
GET /api/v1/imports/{import}/synonyms | Nothing is searchable yet. |
POST /api/v1/imports/{import}/synonyms/check | Nothing is searchable yet, or the engine is unreachable. |
GET /api/v1/search-settings | Nothing is searchable yet. |
GET /api/v1/imports/{import}/search-settings | Nothing is searchable yet. |
GET /api/v1/categories | Nothing is searchable yet. |
POST /api/v1/pages/settings | Nothing is searchable yet. |
POST /api/v1/preview/search | Nothing is searchable yet, or the engine is unreachable. |
POST /api/v1/preview/page | Nothing is searchable yet, or the engine is unreachable. |
POST /api/v1/preview/find | Nothing is searchable yet, or the engine is unreachable. |