Error Reference

All error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "doc_url": "https://buywhere.ai/docs/errors#ERROR_CODE"
  }
}

Error Codes

400 — Bad Request

Example:

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query parameter is missing or empty.",
    "doc_url": "https://buywhere.ai/docs/errors#INVALID_QUERY"
  }
}

401 — Unauthorized

Example:

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass as Authorization: Bearer <key>.",
    "doc_url": "https://buywhere.ai/docs/errors#MISSING_API_KEY"
  }
}

403 — Forbidden

Example:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key does not have the required scope for this endpoint.",
    "doc_url": "https://buywhere.ai/docs/errors#INSUFFICIENT_SCOPE"
  }
}

404 — Not Found

405 — Method Not Allowed

429 — Rate Limit Exceeded

The response includes retry information:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Per-minute rate limit exceeded.",
    "doc_url": "https://buywhere.ai/docs/errors#RATE_LIMIT_EXCEEDED"
  },
  "rate_limit": {
    "retry_after": 45,
    "limit": 60,
    "remaining": 0,
    "reset_at": "2026-05-16T14:45:00Z"
  }
}

How to handle: Wait retry_after seconds before retrying. Use exponential backoff starting at 2 seconds. See Authentication for a retry code example.

422 — Validation Error

500 — Internal Server Error

502 — Bad Gateway

503 — Service Unavailable

HTTP Status Code Summary

Empty-Result Envelope (meta.emptiness_reason)

When an MCP tool or REST API call returns 200 OK with zero products, the response includes an emptiness_reason field in the meta object. This tells agents why the result is empty, so they can decide whether to retry, widen the query, or surface an error to the user.

Note: Non-empty responses (one or more products) MUST NOT carry emptiness_reason per the specification. The field appears only when data/products/results/items arrays are empty.

Enum values

confidence field

Every emptiness_reason comes with a confidence field:

diagnostic block

When emptiness_reason is present, meta.diagnostic provides additional context:

{
  "meta": {
    "emptiness_reason": "no_match",
    "confidence": "high",
    "diagnostic": {
      "engine_status": "ok",
      "indexed_for_region": true,
      "category_recognized": true,
      "rate_limit_remaining": null,
      "deliver_to_present": true
    }
  }
}

Worked examples

REST API (empty query)

curl -s "https://api.buywhere.ai/v1/products/search?q=zzzz_notfound&country_code=US&limit=2" \
  -H "Authorization: Bearer $BUYWHERE_API_KEY"

Response:

{
  "data": [],
  "meta": {
    "total": 0,
    "emptiness_reason": "no_match",
    "confidence": "high",
    "diagnostic": {
      "engine_status": "ok",
      "indexed_for_region": true,
      "category_recognized": false,
      "rate_limit_remaining": null,
      "deliver_to_present": true
    }
  }
}

MCP v2 (invalid deliver_to)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_products_v2",
    "arguments": {
      "q": "laptop",
      "deliver_to": "ZZ",
      "limit": 5
    }
  }
}

Response (note: NOT a JSON-RPC error, a 200 OK with empty results):

{
  "data": [],
  "meta": {
    "emptiness_reason": "invalid_deliver_to",
    "hint": "deliver_to=\"ZZ\" is not a supported country code. Supported: SG, US, VN, TH, MY, GB, IN, AU, PH, ID.",
    "deliver_to": "ZZ"
  }
}

For agents

• Always check for meta.emptiness_reason when the response array is empty.
• When confidence: low: retry once with a backoff ≤2s, then treat as ambiguous.
• When deliver_to_missing: re-issue with the buyer's actual region.
• When quota: respect the rate-limit window; do not storm retries.
• When api_error: log the event and surface to the user as a transient failure.

See also: Agent-DX v2 Wire Reference for the full tool surface.