Zid Docs
  1. Merchant API
Zid Docs
  • Merchant API
    • Start Here 🚀
    • Overview to Zid Apps
    • Authorization
    • Responses
    • Webhooks
    • Rate Limiting
    • APIs
      • Orders
        • Update Order by ID
        • Get Order Credit Notes
        • Get Order by ID
        • List of Orders
      • Reverse Orders
        • Reverse Order Reasons
        • Create Reverse Orders
        • Create Reverse Orders Waybill
        • Add Reverse Order Reasons
      • Carts
        • Get Abandoned Cart Details
        • List Abandoned Carts
      • Products
        • Managing Products
          • Get a Product by ID
          • Retrieve a list of products
          • Create a new product
          • Update an existing product.
          • Bulk update of products using their IDs or SKUs
          • Delete a product.
          • Product Setting
          • List Product Reviews
        • Digital Vouchers
          • Product Vouchers
          • Order Voucher
          • Add Product Voucher
          • Import Vouchers
          • Export Vouchers
          • Update Product Voucher
          • Remove Product Voucher
        • Product Categories
          • Get Single Category Details
          • Get all categories
          • Create Store Category
          • Update a Store Category
          • Add a product to a certain category
          • Publish/Unpublish a Category
          • Detach Category from All Products
          • Remove Category from Product
        • Product Badge
          • Product Badge
        • Product Attributes
          • Get Product Attributes
          • Get Product Attributes
          • Retrieve a product attribute
          • Add a New Product Attribute
          • Add a New Product Attribute
          • Update a product attribute
          • Delete a product attribute
        • Product Attribute Presets
          • Get attribute presets
          • Create Attribute Preset
          • Update Attribute Preset
          • Delete an attribute preset
        • Product Customizations
          • Add Product Variants
          • Insert Custom Options to a Product
          • Insert Custom User-Input Fields to a Product
        • Product Manual Sorting
          • Set Custom Product Order
          • Reset the manual sorting of all products
        • Product Images
          • Get List of images of a product.
          • Add an image to a product
          • Update a product Image Order
          • Delete a product image
        • Product Notifications
          • Availability Notification Stats
          • Availability Notifications Settings
          • List Availability Notifications
          • Add Availability Notification
          • Save Availability Notifications Settings
          • Manually Send Availability Notification Email
          • Export Availability Notifications
        • Product Import
          • Email All Products to Store Owner
          • Import Products via CSV or xlsx File
        • Product Stock (Multi-Inventory)
          • Get Product Stock by ID
          • List Product Stocks
          • Add Product Stock
          • Update Single Product Stock
          • Bulk Update Product Stocks
        • Product Questions & Answers
          • Get Question
          • Get Answer
          • Get All Questions
          • List Question Answers
          • Create Question
          • Create Answer
          • Update Question
          • Update Answer
          • Delete Question
          • Delete Answer
        • Product Reviews
          • List Reviews
          • New Reviews Total
          • Change Review Status
          • Bulk Change all Review Statuses
          • Delete Review
          • Import Product Reviews
          • Reply to Review
          • Delete Reply
          • Update Reply to Review
        • Digital Products
          • Create Downloadable Product
          • Generate an Upload URL
          • Upload File to S3
          • Create Product Downloadables
          • Get Product Downloadables
          • Delete Product Downloadables
          • Get Store Downloadables
          • Create Store Downloadables
          • Delete Store Downloadables
      • Inventories
        • Get Store Location by ID
        • List Store Locations
        • Add a New Location
        • Update a Location by ID
        • Update Products Stock by Location ID
      • Shipping
        • List Store Delivery Options
        • Add Shipping Option
      • Marketing
        • Gift Cards
          • Get Store Settings
          • Add gift card to the cart
          • Update Store Settings
          • Upload gift card designs
          • Remove gift card from the cart
        • Coupons
          • Create a New Coupon
          • List Coupons
          • Get Coupon Details
          • Update Coupon
          • Delete Coupon
        • Bundle Offers
          • Retrieve all Bundle Offers
        • Loyalty Program
          • Customer Wallet
          • Customer Points
          • Loyalty Program Points per Order
          • Store Loyalty Status
          • Redemption Methods
          • Cashback Rules
          • Add Redemption to Cart
          • Remove Redemption from Cart
          • Info Page
          • Loyalty Program Activation
          • Loyalty Status
          • Set Points Expiration
          • Cashback Rule Method Update
          • Cashback Rule Method Update Status
          • Add Points Redemption Method
          • Update Points Redemption Method
          • Delete Points Redemption Method
          • Toggle Redemption Method Status
          • Show Loyalty Points Info for Specific Customer
          • Customer Profile
          • List Data
          • Customer Points History
          • Info Page - Managers
          • Update Info Page
          • Adjust Customer Points
      • Customers
        • List of Customers
        • Get Customer by ID
      • Store Settings
        • 📄 User Roles and Permissions
        • Get Manager's Profile
        • Get VAT Settings
        • List of Payment Method
      • Countries and Cities
        • Retrieve Store Operating Countries
        • Retrieve Cities by Country ID
        • Countries List
      • Webhook
        • List of Webhooks
        • Create a Webhook
        • Delete a Webhook by OriginalId
        • Delete a Webhook by Subscriber
    • Store Events
      • Order
      • Product
      • Abandoned Cart
      • Customer
      • Product Category
  • App API
    • Create your First App
    • Embedded Apps
    • App Scripts
    • App Events
    • App Subscription
      • Get Subscription Details
      • Update Usage-Based Charges
  • Themes
    • 🚨 Important Update: Zid Themes
    • Adding Video URL Feature to Third-Party Themes
    • Landing Page Development
    • Getting Started with Zid Themes
      • Introduction to Theme Development
      • Manage your Themes
      • Building Themes in Zid
      • Theme File Structure
      • Twig Syntax and Features
      • Zid Theme Packager
    • Templates
      • Layout
      • Home Page
      • Products
      • Cart
      • Store Language and Currency
    • Settings Schema
      • Text
      • Number
      • Text-Area
      • Select
      • Radio Buttons
      • Checkbox
      • Range
      • Color
      • Image
      • Product
      • Category
      • List
      • Fieldset
    • Code Snippets
      • Apple Pay Quick Checkout
      • Custom CSS Injection
      • Displaying the Store's Business Center Logo
      • Customizing Copyright Text
      • Store's Main Navigation Menu
      • Customer Wishlist
      • Products
        • Products Badges
        • Product Ratings
        • Remaining Product Stock
        • Sold Items Count
        • Product Filtration by Attributes
        • Grouped Products
        • Product Questions & Answers
        • Product Restock Notfication
      • SEO
        • Images alt text
        • Themes SEO Marketing Tags
      • Marketing
        • Metafields
        • Gift Feature
        • Loyalty Program
    • Zid Themes Library: API Integration
      • Products
      • Product Categories
      • Cart
      • Blog
      • Customer
      • Store Settings
    • Data Reference
      • Locals
      • Store
      • Cart
      • Product
      • Products List
      • Category
      • Categories List
      • Session
      • FAQs
      • Customer
      • Blogs
      • Page
      • Main Menu
      • Main Navigation Menu
      • Request
      • Orders
      • Addresses
      • Store Payment Methods
      • Store Shipping Methods
      • Store Banks
      • Asset URL
      • Header Meta Tags
      • Loyalty pogram Wallet
    • Themes CLI
      • CLI Authentication
      • Theme Create
      • Theme Package
      • Theme Update
      • Themes List
      • Theme Preview
  1. Merchant API

Responses

API Response Codes, Error Handling, and Best Practices
Zid API is built to adhere strictly to REST principles, ensuring seamless communication between clients and our server. Below is a detailed guide to understanding the various HTTP response codes, error handling mechanisms, and best practices to help developers efficiently interact with our API.

Success Response Codes#

We use standard HTTP response codes to indicate the status of API requests. Here’s a breakdown of the success codes:
Color CodeResponseStatusMeaningWhen to Use
#14cc27200OKThe request was successful, and the server returned the requested data.Use this when everything went as expected, and you’re returning data.
#14cc27201CreatedThe request was successful, and a new resource was created.Use this when a new resource has been added to the database.
#14cc27202AcceptedThe request has been accepted for processing, but the processing is not complete.Use this for asynchronous processes where the action hasn’t completed yet.
#14cc27204No ContentThe request was successful, but there is no content to return.Use this when the action has been successfully executed, but there’s no content to send back.

Example Success Response:#

A typical successful response would look like this:
{
  "status": 200,
  "success": true,
  "data": {
    "message": "Request processed successfully.",
    "code": 200
  }
}

Client Error Response Codes#

When a request fails due to client-side issues, the API will return a 4xx error code. Understanding these codes is crucial for diagnosing problems quickly.
Color CodeResponseSlugStatusMeaningTroubleshooting Tips
#fcba03400bad_requestBad RequestThe server could not understand the request due to invalid syntax.Check the request syntax and parameters. Ensure all required fields are included.
#fcba03401unauthorizedUnauthorizedAuthentication is required and has failed or has not yet been provided.Verify API keys or authentication credentials.
#fcba03403forbiddenForbiddenThe server understood the request but refuses to authorize it.Ensure the user has the necessary permissions.
#fcba03404not_foundNot FoundThe requested resource could not be found.Double-check the URL and resource ID.
#fcba03405method_not_allowedMethod Not AllowedThe method specified in the request is not allowed.Verify that you are using the correct HTTP method (GET, POST, etc.).
#fcba03406not_acceptableNot AcceptableThe server cannot produce a response matching the list of acceptable values defined in the request's headers.Adjust the Accept headers in your request.
#fcba03410goneGoneThe resource requested is no longer available and will not be available again.This resource has been permanently removed, and you should clean up references to it.
#fcba03422validation_failedUnprocessable EntityThe server understands the content type and syntax of the request entity, but it was unable to process the contained instructions.Review the data being submitted for missing fields or incorrect formats.
#fcba03429too_many_requestsToo Many RequestsYou have sent too many requests in a given amount of time.Implement retry logic or reduce the request rate.

Example Client Error Response:#

When the request is invalid, you might receive a response like this:
{
  "status": 422,
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Invalid input data.",
    "fields": {
      "email": [
        "Email format is invalid."
      ],
      "password": [
        "Password must be at least 8 characters."
      ]
    }
  }
}

Server Error Response Codes#

Server errors indicate a problem with the server processing the request. These errors are generally not caused by the client.
Color CodeResponseSlugStatusMeaningTroubleshooting Tips
#f03c15500server_errorInternal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.Retry the request later. If the issue persists, contact support.
#f03c15503service_unavailableService UnavailableThe server is not ready to handle the request, often due to temporary overloading or maintenance.Wait and retry the request later.

Example Server Error Response:#

In case of a server error, you might receive the following response:
{
  "status": 500,
  "success": false,
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred. Please try again later."
  }
}

Handling Multiple Errors in 4xx Responses#

When a request results in multiple errors leading to a 4xx response, our API returns a structured response that includes a list of affected fields and an array of associated error messages. This helps in pinpointing the exact issues for each field.

Example of a Single Field Error:#

{
    "status": 422,
    "success": false,
    "error": {
        "code": "خطأ في التحقق",
        "message": "تحتوي بعض الحقول على بيانات غير صحيحة.",
        "fields": {
            "اسم_المستخدم": [
                "اسم المستخدم مطلوب."
            ]
        }
    }
}

Example of Multiple Field Errors:#

{
    "status": 422,
    "success": false,
    "error": {
        "code": "خطأ في التحقق",
        "message": "تحتوي عدة حقول على بيانات غير صحيحة.",
        "fields": {
            "اسم_المستخدم": [
                "اسم المستخدم مطلوب."
            ],
            "البريد_الإلكتروني": [
                "صيغة البريد الإلكتروني غير صحيحة."
            ],
            "كلمة_المرور": [
                "يجب أن تتكون كلمة المرور من 8 أحرف على الأقل."
            ],
            "تأكيد_كلمة_المرور": [
                "تأكيد كلمة المرور غير متطابق."
            ]
        }
    }
}

Best Practices for API Integration#

To ensure smooth interaction with our API, follow these best practices:
1.
Validate Inputs: Always validate inputs before sending a request to minimize errors.
2.
Handle Rate Limits Gracefully: Implement exponential backoff strategies to handle 429 Too Many Requests responses.
3.
Check for Updates: Periodically check for API updates to stay aligned with the latest changes and enhancements.
4.
Use Correct HTTP Methods: Ensure you are using the appropriate HTTP methods (GET, POST, PUT, DELETE) as per the endpoint requirements.
5.
Test in a Safe Environment: Before deploying changes in production, thoroughly test your integration in a development or staging environment.

Troubleshooting Tips for Developers:#

💡Check Response Headers: Often, additional context is provided in response headers. Always review these when debugging issues.
💡Log All Requests: Maintain logs of all requests and responses, particularly during development, to track down issues more efficiently.
Modified at 8 months ago
Previous
Authorization
Next
Webhooks
Built with
On this page
Success Response Codes
Example Success Response:
Client Error Response Codes
Example Client Error Response:
Server Error Response Codes
Example Server Error Response:
Handling Multiple Errors in 4xx Responses
Example of a Single Field Error:
Example of Multiple Field Errors:
Best Practices for API Integration
Troubleshooting Tips for Developers: