API Errors Reference

This guide provides detailed information about PlentyONE API errors you may encounter and how to resolve them.

HTTP Status Codes

400 Bad Request

Meaning: The request was malformed or contains invalid data.

Common Causes:

Invalid JSON payload
Missing required fields
Invalid data types
Field validation failures

Example Error:

{
  "error": {
    "code": 400,
    "message": "Validation failed",
    "validation_errors": [
      {
        "field": "quantity",
        "message": "Must be a positive integer"
      }
    ]
  }
}

Solutions:

Check request payload:

# Enable API debug logging
bin/magento config:set plenty/log_config/is_active_debug 1
bin/magento config:set plenty/log_config/log_level debug

# View API request/response
tail -f var/log/plenty_api.log

Validate data before sending:
- Ensure all required fields are present
- Check data types match API requirements
- Verify field values are within acceptable ranges
Common field validation issues:
- Prices: Must be positive decimals
- Quantities: Must be positive integers
- Dates: Must be in ISO 8601 format (YYYY-MM-DD)
- IDs: Must be valid integers

401 Unauthorized

Meaning: Authentication failed or access token is invalid/expired.

Common Causes:

Invalid username or password
Expired access token
User account disabled
Missing API permissions

Solutions:

Verify credentials:

bin/magento config:show plenty/client_config/username
bin/magento config:show plenty/client_config/url

Test authentication:
```
bin/magento plenty:client:test
```

Refresh access token:

bin/magento plenty:client:token --refresh

Update credentials:

bin/magento config:set plenty/client_config/username "your-username"
bin/magento config:set plenty/client_config/password "your-password" --lock-env
bin/magento cache:flush

Check user permissions in PlentyONE:
- Navigate to Setup → Settings → User → Accounts
- Verify user has API access enabled
- Ensure user account is active
- Check user has required permissions for the operations

403 Forbidden

Meaning: Authenticated successfully but lacks permission for the requested resource.

Common Causes:

Insufficient user permissions
IP address not whitelisted
API endpoint access restricted
Resource ownership mismatch

Solutions:

Check API user permissions:
- In PlentyONE: Setup → Settings → User → Accounts
- Verify user has appropriate rights for:
  - Item management
  - Order management
  - Customer management
  - Property management
Verify IP whitelist:
- Check if PlentyONE has IP restrictions
- Add your server IP to whitelist if required
Contact system administrator:
- May require elevated permissions
- Check if resource access is restricted by policy

404 Not Found

Meaning: The requested resource does not exist.

Common Causes:

Invalid entity ID
Entity deleted in PlentyONE
Incorrect API endpoint
Wrong base URL

Example Errors:

Error: Item with ID 12345 not found
Error: Order with ID 67890 does not exist
Error: Property with ID 100 not found

Solutions:

Verify entity exists in PlentyONE:
- Log into PlentyONE backend
- Search for the entity by ID
- Check if it was deleted or archived

Check API endpoint:

# Verify base URL
bin/magento config:show plenty/client_config/url
# Should be: https://your-domain.plentymarkets-cloud01.com

For product import issues:

# Verify item exists
bin/magento plenty:item:collect -i 12345 --verbose

# If item doesn't exist, create in PlentyONE first

Check entity mapping:

-- Check if entity is mapped
SELECT * FROM softcommerce_plenty_item_relation WHERE plenty_item_id = 12345;
SELECT * FROM softcommerce_plenty_order_relation WHERE plenty_order_id = 67890;

422 Unprocessable Entity

Meaning: Request is well-formed but contains semantic errors or business rule violations.

Common Causes:

Business logic validation failures
Duplicate entity creation
Referential integrity violations
Invalid state transitions

Example Errors:

{
  "error": {
    "code": 422,
    "message": "Cannot create duplicate barcode",
    "details": {
      "barcode": "12345678",
      "existing_item_id": 100
    }
  }
}

Solutions:

Check for duplicates:

# For items with duplicate SKU
mysql> SELECT * FROM catalog_product_entity WHERE sku = 'YOUR-SKU';

# Check PlentyONE for existing records
bin/magento plenty:item:collect --sku=YOUR-SKU

Verify referential integrity:
- Ensure referenced entities exist (categories, attributes, etc.)
- Check foreign key relationships
Review business rules:
- Some operations require specific prerequisites
- Example: Can't export order without valid customer

429 Too Many Requests

Meaning: Rate limit exceeded.

PlentyONE Rate Limits:

Standard: 1000 requests per 5 minutes per user
Peak hours: May be reduced to 500 requests per 5 minutes
Per endpoint: Some endpoints have stricter limits

Solutions:

Implement rate limiting in profiles:

// Profile configuration
'rate_limit' => [
    'enabled' => true,
    'max_requests' => 200,      // Per minute
    'retry_after' => 60,        // Seconds
    'exponential_backoff' => true
]

Reduce batch sizes:
- Navigate to profile configuration
- Reduce collection_size and page_size
- Example: From 500 to 100 items per batch

Schedule operations off-peak:

# Schedule large syncs during off-peak hours (e.g., 2 AM)
0 2 * * * /usr/bin/php /path/bin/magento plenty:item:import

Use queue-based processing:

# Process items asynchronously
bin/magento queue:consumers:start plentyItemExportConsumer --max-messages=100

Monitor rate limit headers:

# Check API logs for rate limit info
tail -f var/log/plenty_api.log | grep "X-RateLimit"

500 Internal Server Error

Meaning: PlentyONE server encountered an unexpected error.

Common Causes:

PlentyONE system issue
Database timeout
Invalid data causing server crash
System maintenance

Solutions:

Check PlentyONE status:
- Visit PlentyONE status page
- Check for scheduled maintenance
- Contact PlentyONE support if persistent

Retry the request:

# Automatic retry is built-in, but you can manually retry
bin/magento plenty:item:export --sku=YOUR-SKU --verbose

Simplify the request:
- Reduce batch size
- Process single entity to isolate issue
- Remove optional fields
Contact PlentyONE support with:
- Timestamp of error
- Request ID (from error response)
- API endpoint accessed
- Request payload (sanitized)

502 Bad Gateway / 503 Service Unavailable

Meaning: PlentyONE service is temporarily unavailable.

Common Causes:

System maintenance
Server overload
Network issues between your server and PlentyONE
CDN/proxy issues

Solutions:

Wait and retry:
- Profile execution includes automatic retry logic
- Default: 3 retry attempts with exponential backoff
Check PlentyONE status:
- Visit status page or support portal
- Check for maintenance notifications

Verify network connectivity:

# Test connectivity
curl -I https://your-domain.plentymarkets-cloud01.com
ping your-domain.plentymarkets-cloud01.com

Adjust timeout settings:

# Increase timeout in profile configuration
bin/magento config:set plenty/client_config/timeout 120

504 Gateway Timeout

Meaning: PlentyONE did not respond within the timeout period.

Common Causes:

Long-running query
Large data set processing
PlentyONE system under heavy load
Network latency

Solutions:

Increase timeout:

# Set higher timeout (in seconds)
bin/magento config:set plenty/client_config/timeout 300
bin/magento cache:flush

Reduce batch size:
- Process smaller batches
- Use pagination more effectively

Optimize filters:

# Instead of fetching all items
bin/magento plenty:item:collect

# Fetch specific date range
bin/magento plenty:item:collect --date-updated="2025-01-01/2025-01-31"

API-Specific Errors

Item/Product Errors

"Variation not found"

Cause: Attempting to update/access a variation that doesn't exist.

Solution:

# Verify variation exists
bin/magento plenty:item:collect -i <item_id> --verbose

# Check variation mappings
mysql> SELECT * FROM softcommerce_plenty_item_variation_relation WHERE plenty_item_id = <item_id>;

"Main variation required"

Cause: Creating item without a main variation.

Solution:

Every item must have at least one main variation
Ensure main variation is created first
Check item export includes main variation data

"Price not found for web store"

Cause: Price configuration missing for target web store.

Solution:

Configure prices in PlentyONE for all web stores
Verify price mapping in profile configuration
Ensure sales prices are activated for web store

Order Errors

"Referrer not found"

Cause: Order referrer (source) not configured.

Solution:

# Create Magento referrer if not exists
bin/magento plenty:setup:create --type=referrer

# Verify referrer in profile config
# SoftCommerce → Profiles → Manage Profiles → [Order Profile] → Configuration
# Set Order Referrer to "magento"

"Payment not created"

Cause: Failed to create payment record in PlentyONE.

Solution:

Check payment method mapping in profile
Verify payment method exists in PlentyONE
Ensure payment amount matches order total

"Contact required"

Cause: Order export requires associated customer/contact.

Solution:

# Export customer first
bin/magento plenty:customer:export --id=<customer_id>

# Then export order
bin/magento plenty:order:export -i <order_id>

Stock Errors

"Warehouse not found"

Cause: Warehouse ID in configuration doesn't exist in PlentyONE.

Solution:

Verify warehouse configuration:

bin/magento plenty:stock:setup:collect --verbose

Update profile configuration with correct warehouse ID
Map Magento sources to PlentyONE warehouses

"Stock type invalid"

Cause: Invalid stock type specified.

Valid stock types:

1 - Physical stock
2 - Reserved stock
3 - Net stock (physical - reserved)

Solution: Update profile configuration to use valid stock type.

Category Errors

"Category tree limit exceeded"

Cause: Category hierarchy too deep (PlentyONE limit: 6 levels).

Solution:

Flatten Magento category structure
Use category mapping to skip intermediate levels
Combine multiple Magento categories into one PlentyONE category

"Category name translation missing"

Cause: Category name not provided for required locale.

Solution:

Ensure all category names are translated in Magento
Configure store-to-locale mapping in profile
Provide default fallback locale

Debugging API Errors

Enable Debug Logging

# Enable debug mode
bin/magento config:set plenty/log_config/is_active_debug 1
bin/magento config:set plenty/log_config/log_level debug
bin/magento cache:flush

View API Logs

# API request/response logs
tail -f var/log/plenty_api.log

# API errors only
tail -f var/log/plenty_api_error.log

# Filter by specific endpoint
tail -f var/log/plenty_api.log | grep "/rest/items"

Analyze API Requests

# View last 50 lines of API log
tail -n 50 var/log/plenty_api.log

# Search for specific error
grep "401 Unauthorized" var/log/plenty_api.log

# View requests for specific SKU
grep "TEST-SKU-001" var/log/plenty_api.log

Test API Endpoints Directly

Use curl to test endpoints outside of Magento:

# 1. Get access token
TOKEN=$(curl -X POST https://your-domain.plentymarkets-cloud01.com/rest/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your-user","password":"your-pass"}' \
  | jq -r '.accessToken')

# 2. Test item endpoint
curl -X GET https://your-domain.plentymarkets-cloud01.com/rest/items/100 \
  -H "Authorization: Bearer $TOKEN"

# 3. Test order endpoint
curl -X GET https://your-domain.plentymarkets-cloud01.com/rest/orders/12345 \
  -H "Authorization: Bearer $TOKEN"

Common Error Patterns

Authentication Loop

Symptoms:

Continuous 401 errors
Token refresh fails repeatedly
"Invalid credentials" despite correct password

Causes:

Password recently changed
User account locked
Multiple failed login attempts

Solutions:

Reset password in PlentyONE
Wait 15 minutes if account locked

Clear stored tokens:

bin/magento config:set plenty/client_config/access_token ""
bin/magento config:set plenty/client_config/refresh_token ""
bin/magento cache:flush

Intermittent 404 Errors

Symptoms:

Entity found sometimes, not found other times
Works manually but fails in cron

Causes:

Entity recently deleted
Asynchronous PlentyONE updates
Caching issues

Solutions:

Add retry logic with delay
Verify entity exists before operations
Check PlentyONE replication status

Data Validation Failures

Symptoms:

400 or 422 errors with validation messages
"Required field missing" errors
Data type mismatch errors

Solutions:

Enable verbose mode to see exact validation errors:

bin/magento plenty:item:export --sku=TEST-SKU --verbose

Check data transformation in logs
Validate data in Magento before export
Review field mapping in profile configuration

Getting Help

If you can't resolve an API error:

Collect diagnostic information:

# System check
bin/magento plenty:system:check > system-check.log

# Recent API logs
tail -n 500 var/log/plenty_api.log > api-logs.txt
tail -n 500 var/log/plenty_api_error.log > api-errors.txt

Document the error:
- Exact error message
- HTTP status code
- Timestamp
- Request details (endpoint, method, payload)
- Steps to reproduce
Contact support with:
- System check output
- Relevant log excerpts
- Error documentation
- Profile configuration (sanitized)

Connection Testing - Test API connectivity
Common Issues - General troubleshooting
Order Issues - Order-specific problems
Profile Issues - Profile execution problems

Pro Tip: Always enable debug logging when troubleshooting API issues. The detailed request/response logs are invaluable for identifying the root cause.

HTTP Status Codes​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

404 Not Found​

422 Unprocessable Entity​

429 Too Many Requests​

500 Internal Server Error​

502 Bad Gateway / 503 Service Unavailable​

504 Gateway Timeout​

API-Specific Errors​

Item/Product Errors​

"Variation not found"​

"Main variation required"​

"Price not found for web store"​

Order Errors​

"Referrer not found"​

"Payment not created"​

"Contact required"​

Stock Errors​

"Warehouse not found"​

"Stock type invalid"​

Category Errors​

"Category tree limit exceeded"​

"Category name translation missing"​

Debugging API Errors​

Enable Debug Logging​

View API Logs​

Analyze API Requests​

Test API Endpoints Directly​

Common Error Patterns​

Authentication Loop​

Intermittent 404 Errors​

Data Validation Failures​

Getting Help​

Related Documentation​

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

502 Bad Gateway / 503 Service Unavailable

504 Gateway Timeout

API-Specific Errors

Item/Product Errors

"Variation not found"

"Main variation required"

"Price not found for web store"

Order Errors

"Referrer not found"

"Payment not created"

"Contact required"

Stock Errors

"Warehouse not found"

"Stock type invalid"

Category Errors

"Category tree limit exceeded"

"Category name translation missing"

Debugging API Errors

Enable Debug Logging

View API Logs

Analyze API Requests

Test API Endpoints Directly

Common Error Patterns

Authentication Loop

Intermittent 404 Errors

Data Validation Failures

Getting Help

Related Documentation