Queek docs

Errors

The one envelope every failure answers in, and every code the Merchant API emits.

The envelope

A failure answers with one envelope, plus the legacy top-level keys older clients read:

{
  "status": "failed",
  "error_code": "insufficient_scope",
  "message": "This API key does not carry the 'merchant-orders-update' scope it was called with.",
  "data": null,
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not carry the 'merchant-orders-update' scope it was called with.",
    "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope",
    "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45"
  }
}

Branch on error.code, never on message. The code is stable — a new failure mode gets a new code, and an existing code never changes meaning — while the message is written for a human and may be reworded. error_code at the top level mirrors error.code for clients that predate the envelope.

error keyAlwaysMeaning
codeyesOne of the codes below.
messageyesHuman-readable. Not stable.
doc_urlyesDeep link to the code's row in the error reference.
request_idyesThe X-Request-Id of the call — quote it in support.
fieldvalidation onlyThe first offending field.
errorsvalidation onlyPer-field messages, { field: [message, …] }.

Validation failures answer 422 validation_failed with the offending fields:

{
  "status": "failed",
  "message": "The quantity change field is required.",
  "error_type": "validation_error",
  "errors": { "quantity_change": ["The quantity change field is required."] },
  "data": null,
  "error": {
    "code": "validation_failed",
    "message": "The quantity change field is required.",
    "field": "quantity_change",
    "errors": { "quantity_change": ["The quantity change field is required."] },
    "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed",
    "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45"
  }
}

The top-level message is the first failing rule; error.errors has all of them.

One refusal predates the envelope and keeps its older shape: a vendor header naming a different store than the key's answers 403 as {"error": "VENDOR_ACCESS_DENIED", "message": "This connection is bound to a different store"}. Switch on that top-level error key for this one code only — everything else is in the envelope above.

Every code

The codes this API emits, drawn from the shared error.code vocabulary in the merchant OpenAPI document (components.schemas.QueekError). The vocabulary also names codes for other surfaces (checkout, the dashboard, assistant tools). The ones this API never returns are listed at the end.

Keys and scopes

error.codeStatusCause
invalid_client_key401The key is unknown. Check it under Dashboard → Settings → Connections.
api_key_mode_mismatch401A _test_ key on a live store, or a _live_ key on a dev store. Keys never cross modes.
api_key_revoked403The key was revoked. Mint a fresh one.
api_key_expired403The key expired. Mint a fresh one.
private_key_required403A public pk_ key was sent. Mint a private sk_ key.
insufficient_scope403The key does not carry the scope this operation needs — including the contact filters on the customer list without merchant-customers-contact-read. The message names the missing scope.
route_not_available403Not part of the Merchant API — the endpoints are exactly those in the reference. A key sent to a retired api/v1/biz/… path is refused here too, with the new /api/v1/merchant/… path named in the message: This dashboard path no longer accepts API keys. Call POST /api/v1/merchant/orders/{order}/status instead. Anything else stays dashboard-only.
plan_inactive403The store's plan has no API access.

Note the two statuses that differ from the Headless API: a revoked or expired key is 403 here, and so is a route outside the Merchant API — the key is valid, the call itself is what is refused.

Cross-store

error.codeStatusCause
VENDOR_ACCESS_DENIED403A vendor header named a different store than the key's. Answers in the older {"error", "message"} shape. Drop the header: the key already names its store.

Request shape

These are the status-implied defaults: the code a status carries when no surface has named the failure more precisely.

error.codeStatusCause
bad_request400The request could not be understood.
unauthenticated401Authentication is required and none that fits was presented.
forbidden403Authenticated, but not allowed to do this.
not_found404No such resource — an id the store does not have, for instance.
method_not_allowed405That method is not supported on this endpoint.
conflict409The request conflicts with the current state.
gone410The resource existed and no longer does.
payload_too_large413The body exceeds the size limit.
unsupported_media_type415Send Content-Type: application/json.
validation_failed422The body or query is invalid; see error.errors.
too_many_requests429Rate limited — honour Retry-After.
server_error500Queek's fault. Retry with backoff and quote the request_id.
service_unavailable503Temporarily unavailable. Retry with backoff.

Idempotency

See Idempotency & rate limits for the full contract.

error.codeStatusCause
idempotency_key_reuse409This Idempotency-Key was already used with a different body. Use a new key.
idempotency_key_in_progress409A request with this key is still running. Retry in a moment; nothing ran twice.

Refunds

The causes and the fields each carries are on the Refunds page.

error.codeStatusCause
idempotency_key_required400A write that must not run twice (a refund, a reply to a shopper) was sent without an Idempotency-Key.
invalid_refund_amount422The refund amount is not positive or has more decimals than the currency.
refund_amount_exceeds_refundable422More than what is left to refund; data.refundable and data.currency give the most.
refund_amount_below_minimum422A refund through the payment provider is below the provider's smallest.
nothing_to_refund422Everything received has already been refunded.
order_not_refundable422The order has received no payment to refund.
refund_payment_not_found422payment is not a received payment of this order.
refund_line_invalid422A refund line is not on the order, or asks for more than was left.
refund_provider_unavailable422Refunds back through the payment provider are switched off for now.
refund_provider_unsupported422The payment cannot be refunded through its provider.
refunds_disabled503Refunds are switched off.

Catalogue writes

error.codeStatusCause
metaobject_reference_invalid422A product write names a metaobject reference that does not resolve.

Apps and references

These codes come from the Apps and write operations. The status travels with the operation, so read it in the reference; the message names the record at fault.

error.codeMeaning
invalid_clientThe app credential was rejected when minting an installation token. Fatal for the app: fix the credential, do not retry in a loop.
app_token_revokedThe app's tokens were revoked, for example because the app was disabled. Stop minting until it is re-enabled.
app_installation_goneThe installation no longer exists. Purge its local data.
app_installation_pendingThe installation is not active yet. Retry later with backoff.
resync_cooldownA resync was requested again inside the per-installation cooldown. Skip it.
unknown_product_ref, unknown_variant_refAn item names a product or variant that is not in this store. The message carries the reference.

Translations

Every translation_* code in this table answers HTTP 422. The message names the locale or key at fault, and on a write the failing item is named in error.errors, for example translations.3.digest. See Translate store content for when each one occurs.

error.codeStatusCause
translation_digest_stale422A translation was written against source text that has since changed. Re-read the item and translate it again. Nothing in the batch was written.
translation_unknown_key422A translation names a key the resource does not have. Nothing in the batch was written.
translation_unknown_locale422A translation names a language the store has not added.
translation_locale_is_primary422The language is the store's source language, never a translation target.
translation_locale_is_default422The language is the store's default; choose another default before you unpublish or remove it.
translation_locale_not_published422Only the source language or a published language can be the default.
translation_max_published_locales422The store already publishes the most languages it can (20).

An unknown resource type, or a resource id that belongs to another store, is 404 not_found.

Machine translation

Raised by POST /translations/machine/quote and POST /translations/machine. Every refusal here happens before any text is translated, so nothing is charged. The fields named in the table travel in data. See Machine translation for the flow.

error.codeStatusCause
machine_translation_off403The merchant switched machine translation off for this app. They can switch it back on in the app's settings.
machine_translation_unavailable503Machine translation is unavailable for the moment. Retry with backoff; nothing was charged.
insufficient_credits402The store does not have the credits the quote needs. data carries credits_needed and credits_available.
quote_expired410The quote is unknown, older than 10 minutes, or was made for another caller. Ask for a new quote.
quote_mismatch409The run names a different locale, mode or set of references than the quote priced.
quote_already_used409The quote was already spent by another run. A quote covers one run.
quote_stale409The store's content grew since the quote, so the run would translate more than it priced. Ask for a new quote.
translation_run_too_large422The job has more source characters than one run may translate. data carries characters and max_characters. Split it into several jobs.
translation_daily_limit429The store reached its machine translation limit for the day. data carries max_characters_per_day and resets_at (midnight UTC).
machine_translation_busy429Too many of the store's jobs are still being settled. Retry in a moment.

The run also answers 400 idempotency_key_required without an Idempotency-Key header (listed under Refunds), 409 idempotency_key_in_progress while the same key is still running, and 403 insufficient_scope when the key or installation lacks merchant-translations-machine. A body with a field other than locale, mode, resources (and quote_id on the run), or with too many resources or keys, is 422 validation_failed.

Other names in the vocabulary (app_embed_not_ready, app_grant_insufficient, app_handoff_failed, app_ip_not_allowed, app_proxy_failed, app_proxy_gone, channel_gateway_unreachable, requires_slot, subscription_feature_locked) belong to app hosting, sales channels and plan gating. Treat any code you do not recognise by its status class, and log request_id.

Never emitted here

The shared envelope vocabulary names codes for surfaces this API is not. You will not meet them on a key call, and no retry or scope will produce them:

  • origin_required, origin_not_allowed — public-key origin checks. A pk_ key is refused with private_key_required before any origin is looked at.
  • client_key_required — no merchant operation names it; a call with no key at all is refused as unauthenticated.
  • ai_unavailable_in_test_mode — an assistant action in the dashboard; no Merchant API operation emits it.
  • transaction_pin_required, pin_required, invalid_pin — the store transaction PIN a dashboard session confirms money-moving actions with. A key or an app is never asked for it, so a refund made with a key never meets these.
  • payment_amount_mismatch — checkout's verdict, never this API's. Fulfil on the orders/paid webhook, not on anything here.
  • custom_gateway_forbidden, custom_gateway_plan_required, custom_gateway_kyc_required, custom_gateway_store_ineligible, custom_gateway_not_verified, custom_gateway_not_configured, custom_gateway_verification_failed — the dashboard's own errors for a merchant collecting through its own provider account.
  • vendor_mail_sender_forbidden, vendor_mail_sender_not_configured, vendor_mail_sender_plan_required, vendor_mail_sender_verification_failed — the dashboard's mail-sender setup, not on the Merchant API.
  • vendor_mail_sender_key_unavailable, custom_domain_provisioning_failed, unknown_service — in the shared vocabulary, but no Merchant API operation documents them.
  • metafield_definition_missing, metafield_filter_unsupported_type, metafield_namespace_reserved, metafield_value_invalid, metaobject_definition_missing, metaobject_field_invalid, metaobject_type_reserved — catalogue-validation codes from other surfaces; the reference documents exactly which fields each operation validates.

Retries that are safe

GET calls are safe to retry as they are. For writes, send an Idempotency-Key header — every write in the reference lists it as a parameter. Retrying the same key with the same body replays the stored response instead of acting twice; the same key with a different body is refused, which is the point of the header. Failures are never stored, so a retry after an error is a real retry.

When you need help

Quote the request_id from the failing response if it carries one — it is the correlation id that ties your call to Queek's own logs. You may also send your own with the X-Request-Id header (8–128 characters of A-Za-z0-9_.:-) and it will be used as-is.

On this page