Error codes
Every Open Brand Exchange API answers errors as application/problem+json with a machine-readableobx_error and type = https://openbrandexchange.com/errors/<obx_error>, the pages below. Software must handle codes it does not know by their HTTP status.
| obx_error | HTTP | Meaning |
|---|---|---|
invalid_request | 400 | malformed request (JSON, NDJSON, multipart, query) |
validation_failed | 422 | body is well-formed but invalid; see errors[] |
unauthorized | 401 | no credentials |
invalid_token | 401 | expired or unknown token |
access_revoked | 401 | client revoked, retailer blocked or ingest token revoked |
insufficient_scope | 403 | token lacks the scope |
forbidden | 403 | not allowed (role, brand restriction, feature disabled by the brand) |
not_found | 404 | does not exist or is not visible to the caller |
method_not_allowed | 405 | method not supported on an existing path (SHOULD; a node MAY answer 404 not_found instead) |
conflict | 409 | state conflict (not pending, still has children, concurrent job) |
precondition_failed | 412 | If-Match did not match |
payload_too_large | 413 | body above the node's limit |
unsupported_media_type | 415 | content type not accepted |
rate_limited | 429 | slow down; see Retry-After |
limit_exceeded | 400 | too many items (GTINs, selection, sync zip, batch) |
cursor_invalid | 400 | cursor malformed or from another node |
cursor_expired | 410 | restart /changes without a cursor |
export_expired | 410 | export or download job files were deleted |
original_not_allowed | 403 | originals are not available to this caller |
invalid_gtin | 422 | GTIN has a wrong length or check digit |
gtin_conflict | 409 | GTIN already belongs to another variant in this node |
position_conflict | 409 | another asset of this product and colour has this position |
checksum_mismatch | 422 | uploaded bytes do not match the declared sha256 |
blob_missing | 422 | referenced sha256 has not been uploaded |
upload_incomplete | 409 | multipart upload has missing parts |
unknown_parent | 422 | referenced brand or product does not exist |
files_missing | 422 | an import references an image that was not provided |
import_invalid | 422 | import file unreadable (not a CSV/zip, no header, unsafe zip entry) |
mass_unpublish_refused | 409 | mirror import would unpublish more than half of the brand's products |
unsafe_url | 422 | URL resolves to a private/loopback/link-local address or is not https |
csrf_failed | 403 | admin API: missing or wrong X-CSRF-Token |
invalid_credentials | 401 | admin API: wrong e-mail or password |
account_blocked | 403 | admin API: account or retailer blocked |
setup_required | 409/503 | node has not completed first-run setup |
setup_completed | 409 | first-run setup was already done |
invite_invalid | 400 | invite or reset token unknown, used or expired |
not_implemented | 501 | optional capability not offered |
internal_error | 500 | unexpected server error |
service_unavailable | 503 | temporarily unavailable; retry later |
Source: the error table of protocol.md. The OpenAPI descriptions are in theAPI reference.