API errors and integration troubleshooting

HTTP Status Codes

Error Response Format

All error responses follow this format:

{
  "success": false,
  "error": "Human-readable error message"
}

Validation errors (422) may include field-level details:

{
  "success": false,
  "error": "The given data was invalid.",
  "errors": {
    "status": ["The selected status is invalid."],
    "stock_qty": ["The stock qty must be at least 0."]
  }
}

Authentication Errors (401)

"API key required"

Cause: No API key was provided in the request.

Fix: Include your key in one of these headers:

X-API-Key: sk_your_key_here

or

Authorization: Bearer sk_your_key_here

"Invalid or expired API key"

Cause: The key doesn't exist, was deleted, is disabled, or has passed its expiration date.

Fix:

• Check for typos in the key.
• Go to Settings > API Keys and verify the key is active and not expired.
• If the key was deleted, create a new one.

Permission Errors (403)

"Insufficient permissions. Required: orders:write"

Cause: Your API key has the correct authentication but lacks the specific permission needed for this endpoint.

Fix: Go to Settings > API Keys, delete the current key, and create a new one with the required permissions.

"Organization account is inactive"

Cause: Your SalesPro Hub account has been suspended or deactivated.

Fix: Contact your account administrator or SalesPro Hub support.

"API access is not available on the current plan"

Cause: The API is only available on Professional and Enterprise plans.

Fix: Upgrade your subscription at Settings > Billing.

Validation Errors (422)

Order Status Updates

"Cannot transition from 'delivered' to 'confirmed'"

Order statuses can only move forward through the lifecycle. Valid transitions:

Inventory Updates

"The stock qty must be at least 0"

Stock quantities cannot be negative. If you need to represent a backorder, set stock to 0.

"SKU 'XYZ' not found" (in bulk update)

The SKU doesn't match any active product in SalesPro Hub. Check:

• SKU is spelled correctly (case-sensitive).
• The product exists and is active in SalesPro Hub.

Rate Limiting (429)

"Daily API call limit exceeded"

The daily counter resets at midnight UTC. The response includes Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers. External routes also apply a 60-request-per-minute throttle. If you're hitting a limit:

• Reduce polling frequency (every 15 min instead of every 1 min).
• Use ?updated_since= for incremental sync instead of fetching all orders.
• Use bulk endpoints instead of individual updates.

Webhook Troubleshooting

Webhook not being received

1. Check endpoint URL — Is it publicly accessible? Test with curl from an external machine.
2. Check endpoint is enabled — Go to Settings > Webhooks and verify it shows "Active".
3. Check event subscription — The endpoint must be subscribed to the specific event.
4. Check delivery history — Settings > Webhooks > View Deliveries shows all attempts.
5. Check for auto-disable — After 10 consecutive failures, the endpoint is automatically disabled.

Webhook signature verification failing

1. Use the raw request body — Don't parse JSON before verifying. The signature is computed on the raw string.
2. Use the correct secret — Each endpoint has its own secret. They are not interchangeable.
3. Check timestamp format — X-Webhook-Timestamp is a Unix timestamp (seconds since epoch), not ISO 8601.
4. Verify the signed payload format — It's {timestamp}.{raw_body} with a literal period between them.

Webhook endpoint auto-disabled

After 10 consecutive failures, the endpoint is disabled to prevent continued failed deliveries.

To re-enable:

1. Go to Settings > Webhooks.
2. Fix the underlying issue (endpoint URL, server error, etc.).
3. Click the toggle to re-enable.
4. Click "Send Test" to verify it's working.

This resets the failure counter back to 0.

Common Integration Issues

Orders appear in SalesPro Hub but not in the API

• Orders must be submitted (status: pending or later) to appear in the API. Draft orders are internal to SalesPro Hub.
• Verify your API key has orders:read permission.
• Check your query filters — ?status=pending&acknowledged=true would return nothing if orders haven't been acknowledged yet.

Stock levels don't match between systems

Stock in SalesPro Hub changes due to:

• Order submissions — Stock is reserved (increases reserved_qty).
• Order deliveries — Reserved stock is deducted (decreases stock_qty).
• Order cancellations — Reserved stock is released (decreases reserved_qty).
• Manual adjustments — Admins can adjust stock in the dashboard.
• API syncs — Your external system pushes updates.

Use the stock movements endpoint to audit changes:

GET /api/v1/inventory/movements?sku=WDG-001

Duplicate orders in Sage

Use the acknowledge endpoint to prevent reprocessing:

1. After creating the order in Sage, immediately call POST /acknowledge with the Sage reference.
2. Always poll with ?acknowledged=false to skip already-processed orders.
3. Store the SalesPro Hub order_number in Sage as a cross-reference.

Timeout errors

API requests have a 30-second timeout. For large inventories:

• Use pagination: ?per_page=100 for order and inventory listing.
• Limit bulk updates to 500 products per request.
• Use ?updated_since= for incremental order polling instead of full listing.

Getting Help

If you're stuck:

1. Check the delivery history (Settings > Webhooks > View Deliveries) for error details.
2. Use the stock movements endpoint to audit inventory changes.
3. Test your API key with a simple GET /api/v1/orders call using cURL.
4. Contact support through the SalesPro Hub dashboard.