Error handling - Shoppex

This page is reference material.If you are troubleshooting a theme workflow, start with the workflow pages first:

Then come back here if you need the exact error shape or status-code meaning.

Error response format

All errors follow a consistent structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "doc_url": "https://docs.shoppex.io/api-reference/errors",
    "details": [
      { "field": "email", "message": "must be a valid email" }
    ]
  }
}

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable description
`subcode`	string	Stable domain-specific refusal code (optional)
`doc_url`	string	Link to relevant documentation
`details`	array	Field-level validation errors (optional)

HTTP status codes

Code	Name	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Success with no response body, for example DELETE
`400`	Bad Request	Domain-specific or business rule error
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid key but insufficient permissions
`404`	Not Found	Resource does not exist
`422`	Validation Error	Invalid field values
`429`	Too Many Requests	You went over the rate limit
`500`	Server Error	Something went wrong on our end

Error codes reference

Payment coupon errors

POST /dev/v1/payments rejects an invalid coupon with 422 VALIDATION_ERROR and an error.subcode such as coupon_invalid, coupon_expired, coupon_exhausted, or coupon_min_order. No invoice is created. Product- and variant-scoped coupons return coupon_requires_products, and coupons restricted to payment methods return coupon_gateway_restricted; use POST /dev/v1/orders with catalog items for both. See the full coupon error table.

Order product errors

POST /dev/v1/orders takes the product id or its uniqid in items[].product_id. A product the shop does not have, or a deleted one, returns 422 VALIDATION_ERROR with error.subcode = "product_not_found" and one error.details entry per unknown item, for example { "field": "items.1.product_id", "message": "Product not found: prod_x." }. No order is created.

Authentication errors

UNAUTHORIZED

HTTP 401. The API key is missing or invalid.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Solution: Check that your API key is correct and included in the Authorization header.

FORBIDDEN (missing scope)

HTTP 403. Your API key is valid but lacks the required scope for this endpoint.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required API scope.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Solution: Go to Settings → API Keys, check which scopes your key has, and add the missing one. Use GET /me/capabilities to inspect active scopes at runtime.

FORBIDDEN (shop suspended)

HTTP 403. Your shop has been suspended by Shoppex.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Your shop has been suspended.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Solution: Reach out through the Shoppex Discord or Telegram to resolve the suspension. This is an account-level issue, not a key configuration problem.

Validation errors

VALIDATION_ERROR

HTTP 422. One or more fields failed validation.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "email", "message": "must be a valid email" },
      { "field": "price", "message": "must be a positive number" }
    ]
  }
}

Solution: Check the details array for specific field errors.

What each request error means

Use the status code as the first signal:

422 VALIDATION_ERROR means the request shape or field values are invalid
400 means the request was understood, but a business rule rejected it
404 ROUTE_NOT_FOUND means the method and /dev/v1/* path do not match a Developer API endpoint
404 can be generic NOT_FOUND or resource-specific like PRODUCT_NOT_FOUND

For example, a wrong email format on POST /customers returns 422 VALIDATION_ERROR. An expired license on POST /licenses/validate returns 400 LICENSE_EXPIRED. An unknown endpoint such as GET /shops/shop_123/revenue returns 404 ROUTE_NOT_FOUND. A missing product on GET /products/prod_xyz returns 404 PRODUCT_NOT_FOUND.

Theme workflow troubleshooting

If you are using the theme automation flow:

401 usually means your API key is missing or invalid
403 usually means your key is missing themes.read or themes.write
422 usually means the request body or params are wrong
500 usually means the server failed while validating, previewing, publishing, or reading the theme

The most common mistake: theme.inspect fails with 403 because your key is missing themes.read, and theme.apply fails with 403 because it needs themes.write. A 422 usually means a bad request body or theme id. A 500 means something broke on the server. Check the error and retry.

Resource errors

ROUTE_NOT_FOUND

HTTP 404. The HTTP method and /dev/v1/* path do not match a Developer API endpoint. Authentication is not attempted because no route was selected.

{
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "No Developer API route matches GET /dev/v1/shops/shop_123/revenue.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Solution: Compare the method and path with the API Reference. The current shop comes from the API key, so shop-scoped endpoints do not require a shop ID unless their reference explicitly shows one.

NOT_FOUND

HTTP 404. The requested resource does not exist.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Requested resource not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Solution: Verify the resource ID is correct.

PRODUCT_NOT_FOUND

HTTP 404. Specific product not found.

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product with ID 'prod_xyz' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

INVOICE_NOT_FOUND

HTTP 404. Specific invoice not found.

{
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with ID 'inv_abc' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

PAYMENT_NOT_FOUND

HTTP 404. Payment not found.

{
  "error": {
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment with ID 'pay_xyz' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

CUSTOMER_NOT_FOUND

HTTP 404. Customer not found.

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer with ID 'cust_abc' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

CATEGORY_NOT_FOUND

HTTP 404. Category not found.

{
  "error": {
    "code": "CATEGORY_NOT_FOUND",
    "message": "Category with ID 'cat_xyz' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

COUPON_NOT_FOUND

HTTP 404. Coupon not found.

{
  "error": {
    "code": "COUPON_NOT_FOUND",
    "message": "Coupon with ID 'coup_abc' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

SUBSCRIPTION_NOT_FOUND

HTTP 404. Subscription not found.

{
  "error": {
    "code": "SUBSCRIPTION_NOT_FOUND",
    "message": "Subscription with ID 'sub_xyz' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

TICKET_NOT_FOUND

HTTP 404. Support ticket not found.

{
  "error": {
    "code": "TICKET_NOT_FOUND",
    "message": "Ticket with ID 'tkt_abc' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

REVIEW_NOT_FOUND

HTTP 404. Review not found.

{
  "error": {
    "code": "REVIEW_NOT_FOUND",
    "message": "Review with ID 'rev_xyz' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

ESCROW_NOT_FOUND

HTTP 404. Escrow transaction not found.

{
  "error": {
    "code": "ESCROW_NOT_FOUND",
    "message": "Escrow with ID 'esc_abc' not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

License errors

LICENSE_NOT_FOUND

HTTP 404. License key not found.

{
  "error": {
    "code": "LICENSE_NOT_FOUND",
    "message": "License key not found",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

LICENSE_INVALID

HTTP 400. License key is invalid or malformed.

{
  "error": {
    "code": "LICENSE_INVALID",
    "message": "Invalid license key format",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

LICENSE_EXPIRED

HTTP 400. License key has expired.

{
  "error": {
    "code": "LICENSE_EXPIRED",
    "message": "License key has expired",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

LICENSE_HWID_MISMATCH

HTTP 400. Hardware ID does not match the registered device.

{
  "error": {
    "code": "LICENSE_HWID_MISMATCH",
    "message": "Hardware ID mismatch. License is bound to a different device.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Coupon errors

COUPON_EXPIRED

HTTP 400. Coupon has expired.

{
  "error": {
    "code": "COUPON_EXPIRED",
    "message": "This coupon has expired",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

COUPON_MAX_USES_REACHED

HTTP 400. Coupon has reached maximum uses.

{
  "error": {
    "code": "COUPON_MAX_USES_REACHED",
    "message": "This coupon has reached its maximum number of uses",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Idempotency errors

Idempotency key reuse

HTTP 422 VALIDATION_ERROR. Shoppex did not run the request because its idempotency key cannot be used for it:

the key was already used with a different request body on the same route
the first request with this key is still running (Idempotency-Status: processing)
the first request with this key may have completed, but Shoppex has no stored response for it (Idempotency-Status: cached)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "This Idempotency-Key was already used with a different request payload.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

POST /dev/v1/products/{id}/serials/claim answers the same cases with HTTP 409 and the code idempotency_conflict. Solution: Each unique request body needs its own idempotency key. If you are retrying a failed request, make sure the body matches the original. If the request is still processing, retry with the same key after a short wait. See the Idempotency section for details.

SERVICE_UNAVAILABLE

HTTP 503. You sent an idempotency key, but Shoppex could not check it right now. The request did not run.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The Idempotency-Key could not be checked, so the request was not run. Retry with the same key.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Solution: Retry the same request with the same idempotency key after a short wait.

Revision errors

Workflows and coupons return a revision number. It goes up by one on every change. To update or delete one of them only if nobody changed it since you read it, send that number in the If-Match header, for example If-Match: "3".

REVISION_CONFLICT

HTTP 409. The resource changed after you read it. Shoppex changed nothing, and the idempotency key of the request is still free.

{
  "error": {
    "code": "REVISION_CONFLICT",
    "message": "The resource changed since it was read. Read it again and send its current revision in If-Match.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors",
    "current_revision": 4
  }
}

Solution: Read the resource again, check that your change still applies, and send it with the new revision. A retry with an idempotency key that already completed returns the stored response, even if its If-Match is now old.

INVALID_IF_MATCH

HTTP 400. The If-Match header is not a revision number. The request did not run. Solution: Send the revision from your last read, for example If-Match: "3".

Rate limiting

RATE_LIMITED

HTTP 429. Too many requests.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after the reset window.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Response headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After when blocked

Rate limits are plan-dependent, so treat any numeric values you see elsewhere as illustrative. Check the response headers from your own requests for your current limits. Solution: Wait for Retry-After or X-RateLimit-Reset before retrying.

Handling errors in code

Every Dev API error response also returns X-Request-Id in the headers. Log that value together with error.code when you need support or want to trace a failing request.

async function createPayment(title: string, email: string, value: number) {
  const response = await fetch('https://api.shoppex.io/dev/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ title, email, value, currency: 'USD' })
  });

  const result = await response.json();

  if (!response.ok) {
    const error = result.error;

    switch (error.code) {
      case 'VALIDATION_ERROR':
        // Handle field-level errors
        error.details?.forEach(d => console.error(`${d.field}: ${d.message}`));
        break;
      case 'RATE_LIMITED':
        // Wait and retry
        const retryAfter = Number(response.headers.get('retry-after') ?? '2');
        console.log(`Rate limited. Waiting ${retryAfter}s before retry...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        return createPayment(title, email, value);
      case 'UNAUTHORIZED':
        console.error('Invalid API key');
        break;
      default:
        console.error(`Error: ${error.message}`);
    }

    throw new Error(error.message);
  }

  return result.data;
}

import requests
import time

def create_payment(title: str, email: str, value: float):
    response = requests.post(
        'https://api.shoppex.io/dev/v1/payments',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        },
        json={'title': title, 'email': email, 'value': value, 'currency': 'USD'}
    )

    result = response.json()

    if not response.ok:
        error = result['error']

        if error['code'] == 'VALIDATION_ERROR':
            for detail in error.get('details', []):
                print(f"{detail['field']}: {detail['message']}")
        elif error['code'] == 'RATE_LIMITED':
            retry_after = int(response.headers.get('retry-after', '2'))
            print(f"Rate limited. Waiting {retry_after}s before retry...")
            time.sleep(retry_after)
            return create_payment(title, email, value)  # Retry

        raise Exception(error['message'])

    return result['data']

Best practices

Log error codes

Always log the error.code for debugging. It is more reliable than parsing messages.

Handle 429s gracefully

Implement exponential backoff for rate limits. Check X-RateLimit-Reset header.

Validate before sending

Validate inputs client-side to catch errors early and reduce API calls.

Use idempotency keys

For payment creation, use idempotency keys to safely retry failed requests.

​Error response format

​HTTP status codes

​Error codes reference

​Payment coupon errors

​Order product errors

​Authentication errors

​UNAUTHORIZED

​FORBIDDEN (missing scope)

​FORBIDDEN (shop suspended)

​Validation errors

​VALIDATION_ERROR

​What each request error means

​Theme workflow troubleshooting

​Resource errors

​ROUTE_NOT_FOUND

​NOT_FOUND

​PRODUCT_NOT_FOUND

​INVOICE_NOT_FOUND

​PAYMENT_NOT_FOUND

​CUSTOMER_NOT_FOUND

​CATEGORY_NOT_FOUND

​COUPON_NOT_FOUND

​SUBSCRIPTION_NOT_FOUND

​TICKET_NOT_FOUND

​REVIEW_NOT_FOUND

​ESCROW_NOT_FOUND

​License errors

​LICENSE_NOT_FOUND

​LICENSE_INVALID

​LICENSE_EXPIRED

​LICENSE_HWID_MISMATCH

​Coupon errors

​COUPON_EXPIRED

​COUPON_MAX_USES_REACHED

​Idempotency errors

​Idempotency key reuse

​SERVICE_UNAVAILABLE

​Revision errors

​REVISION_CONFLICT

​INVALID_IF_MATCH

​Rate limiting

​RATE_LIMITED

​Handling errors in code

​Best practices

Log error codes

Handle 429s gracefully

Validate before sending

Use idempotency keys

Error response format

HTTP status codes

Error codes reference

Payment coupon errors

Order product errors

Authentication errors

UNAUTHORIZED

FORBIDDEN (missing scope)

FORBIDDEN (shop suspended)

Validation errors

VALIDATION_ERROR

What each request error means

Theme workflow troubleshooting

Resource errors

ROUTE_NOT_FOUND

NOT_FOUND

PRODUCT_NOT_FOUND

INVOICE_NOT_FOUND

PAYMENT_NOT_FOUND

CUSTOMER_NOT_FOUND

CATEGORY_NOT_FOUND

COUPON_NOT_FOUND

SUBSCRIPTION_NOT_FOUND

TICKET_NOT_FOUND

REVIEW_NOT_FOUND

ESCROW_NOT_FOUND

License errors

LICENSE_NOT_FOUND

LICENSE_INVALID

LICENSE_EXPIRED

LICENSE_HWID_MISMATCH

Coupon errors

COUPON_EXPIRED

COUPON_MAX_USES_REACHED

Idempotency errors

Idempotency key reuse

SERVICE_UNAVAILABLE

Revision errors

REVISION_CONFLICT

INVALID_IF_MATCH

Rate limiting

RATE_LIMITED

Handling errors in code

Best practices