Errors

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.

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, identical to the error.code enum in the merchant OpenAPI document (components.schemas.QueekError). Codes the shared vocabulary defines for other surfaces — the dashboard, checkout, AI tools — are listed at the end, so nothing in the enum is unaccounted for.

Keys and scopes

Note the two statuses that differ from the Storefront 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

Request shape

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

Idempotency

See Idempotency & rate limits for the full contract.

Catalogue writes

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 — no AI route is on the Merchant API.
• 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.
• 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.