Partner API v1

Error Codes

BaZaaRDan Partner API, tüm endpointlerde standart JSON hata formatı döndürür. Bu sayfa authentication, permission, validation, inventory, order ve webhook hatalarını açıklar.

ERROR Standard API Errors

Format JSON

Scope All Partner API endpoints

Version Partner API v1

Standard Error Format

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed."
  }
}

Validation Error Format

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request payload validation failed.",
    "details": [
      {
        "field": "items.0.stock",
        "message": "Stock must be an integer greater than or equal to 0."
      }
    ]
  }
}

Authentication Errors

Code	HTTP	Description	Fix
MISSING_API_KEY	401	X-BZ-CLIENT-ID header is missing.	Send Client ID header.
INVALID_API_KEY	401	Client ID is invalid or disabled.	Check app credentials.
MISSING_SIGNATURE	401	X-BZ-SIGNATURE header is missing.	Generate HMAC signature.
INVALID_SIGNATURE	401	HMAC signature could not be verified.	Check canonical string and Client Secret.
INVALID_TIMESTAMP	401	Timestamp is outside allowed tolerance.	Sync server clock and send current Unix timestamp.
INVALID_SIGNATURE	401	Signature is missing, reused or invalid.	Send a unique signature for every request.

Permission Errors

Code	HTTP	Description	Fix
PERMISSION_DENIED	403	Installed app does not have permission for this resource.	Request required permission scope.
APP_NOT_INSTALLED	403	The app is not installed for the seller.	Install or reconnect app.
SELLER_SCOPE_REQUIRED	403	Resource requires seller-level access.	Use credentials connected to the correct seller.

Request Errors

Code	HTTP	Description	Fix
INVALID_JSON	400	Request body is not valid JSON.	Send valid JSON with Content-Type: application/json.
INVALID_PAYLOAD	400	Request body structure is invalid.	Check endpoint request schema.
VALIDATION_ERROR	422	One or more fields failed validation.	Read error.details and fix the fields.
UPDATE_FIELD_REQUIRED	422	No updatable field was provided.	Send stock, price or another supported update field.
IDENTIFIER_REQUIRED	422	No product or variant identifier was provided.	Send product_id, product_sku, variant_combination_id or variant_sku.

Order Errors

Code	HTTP	Description	Fix
ORDER_NOT_FOUND	404	Order does not exist or is not visible to the app.	Check order ID and seller scope.
ORDER_ITEM_NOT_FOUND	404	Order item could not be found.	Check item ID.

Product & Inventory Errors

Code	HTTP	Description	Fix
PRODUCT_NOT_FOUND	404	Main product could not be found.	Check product_id, product_sku or product_barcode.
VARIANT_NOT_FOUND	404	Variant combination could not be found.	Check variant_combination_id, variant_sku or variant_barcode.
SKU_NOT_FOUND	404	No product or variant found for the provided SKU.	Check SKU value and whether it belongs to product or variant level.
BARCODE_NOT_FOUND	404	No product or variant found for the provided barcode.	Check barcode value and whether it belongs to product or variant level.
NEGATIVE_STOCK_NOT_ALLOWED	422	Stock value cannot be negative.	Send stock greater than or equal to 0.
INVALID_PRICE	422	Price value is invalid.	Send a valid decimal price.

Rate Limit Errors

Code	HTTP	Description	Fix
RATE_LIMITED	429	Too many requests in a short period.	Back off and retry after the given Retry-After header.

Webhook Errors

Code	Description	When It Happens
WEBHOOK_DELIVERY_FAILED	Webhook endpoint did not return a successful response.	Partner endpoint returned non-2xx or timed out.
WEBHOOK_SIGNATURE_INVALID	Partner could not verify webhook signature.	Secret mismatch or wrong raw body used for verification.
WEBHOOK_RETRY_EXHAUSTED	Webhook delivery reached max retry attempts.	Partner endpoint stayed unavailable.

HTTP Status Summary

HTTP Status	Meaning
200	Request completed successfully.
400	Malformed request.
401	Authentication failed.
403	Permission denied.
404	Resource not found.
422	Validation error.
429	Rate limit exceeded.
500	Internal server error.

Retry Guidance

Error Type	Should Retry?	Recommended Action
401 / 403	No	Fix credentials or permission scope.
404	No	Check resource identifier.
422	No	Fix request payload.
429	Yes	Retry after Retry-After header.
500	Yes	Retry with exponential backoff.