Skip to main content

​
Error Response Format

All errors follow a consistent structure: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "doc_url": "https://docs.shoppex.io/api/errors#VALIDATION_ERROR",
    "details": [
      { "field": "email", "message": "must be a valid email" }
    ]
  }
}
FieldTypeDescription
codestringMachine-readable error code
messagestringHuman-readable description
doc_urlstringLink to relevant documentation
detailsarrayField-level validation errors (optional)

​
HTTP Status Codes

CodeNameDescription
200OKRequest succeeded
201CreatedResource created successfully
204No ContentSuccess with no response body (e.g., DELETE)
400Bad RequestInvalid request syntax
401UnauthorizedMissing or invalid API key
403ForbiddenValid key but insufficient permissions
404Not FoundResource doesn’t exist
422Validation ErrorInvalid field values
429Too Many RequestsRate limit exceeded
500Server ErrorSomething went wrong on our end

​
Error Codes Reference

​
Authentication Errors

HTTP 401 - API key is missing or invalid.
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Solution: Check that your API key is correct and included in the Authorization header.
HTTP 403 - API key is valid but your shop is suspended or doesn’t have access.
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Shop is suspended"
  }
}
Solution: Contact support to resolve account issues.

​
Validation Errors

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.

​
Resource Errors

HTTP 404 - The requested resource doesn’t exist.
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product with ID 'prod_xyz' not found"
  }
}
Solution: Verify the resource ID is correct.
HTTP 404 - Specific product not found.
{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product with ID 'prod_xyz' not found"
  }
}
HTTP 404 - Specific invoice not found.
{
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with ID 'inv_abc' not found"
  }
}
HTTP 404 - Payment not found.
{
  "error": {
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment with ID 'pay_xyz' not found"
  }
}
HTTP 404 - Customer not found.
{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer with ID 'cust_abc' not found"
  }
}
HTTP 404 - Category not found.
{
  "error": {
    "code": "CATEGORY_NOT_FOUND",
    "message": "Category with ID 'cat_xyz' not found"
  }
}
HTTP 404 - Coupon not found.
{
  "error": {
    "code": "COUPON_NOT_FOUND",
    "message": "Coupon with ID 'coup_abc' not found"
  }
}
HTTP 404 - Subscription not found.
{
  "error": {
    "code": "SUBSCRIPTION_NOT_FOUND",
    "message": "Subscription with ID 'sub_xyz' not found"
  }
}
HTTP 404 - Support ticket not found.
{
  "error": {
    "code": "TICKET_NOT_FOUND",
    "message": "Ticket with ID 'tkt_abc' not found"
  }
}
HTTP 404 - Review not found.
{
  "error": {
    "code": "REVIEW_NOT_FOUND",
    "message": "Review with ID 'rev_xyz' not found"
  }
}
HTTP 404 - Escrow transaction not found.
{
  "error": {
    "code": "ESCROW_NOT_FOUND",
    "message": "Escrow with ID 'esc_abc' not found"
  }
}

​
License Errors

HTTP 404 - License key not found.
{
  "error": {
    "code": "LICENSE_NOT_FOUND",
    "message": "License key not found"
  }
}
HTTP 400 - License key is invalid or malformed.
{
  "error": {
    "code": "LICENSE_INVALID",
    "message": "Invalid license key format"
  }
}
HTTP 400 - License key has expired.
{
  "error": {
    "code": "LICENSE_EXPIRED",
    "message": "License key has expired"
  }
}
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."
  }
}

​
Coupon Errors

HTTP 400 - Coupon has expired.
{
  "error": {
    "code": "COUPON_EXPIRED",
    "message": "This coupon has expired"
  }
}
HTTP 400 - Coupon has reached maximum uses.
{
  "error": {
    "code": "COUPON_MAX_USES_REACHED",
    "message": "This coupon has reached its maximum number of uses"
  }
}

​
Rate Limiting

HTTP 429 - Too many requests.
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later."
  }
}
Solution: Wait a moment before retrying your request.

​
Handling Errors in Code

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
        console.log('Rate limited. Waiting before retry...');
        await new Promise(r => setTimeout(r, 5000));
        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;
}

​
Best Practices

Log Error Codes

Always log the error.code for debugging. It’s 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.