Troubleshooting Guide

This guide helps you diagnose and resolve common issues when using the Spreetail Channel Integration API.

Common Issues

Authentication Problems

Issue: "Invalid credentials" error

Symptoms:

• Receiving 401 Unauthorized with "Invalid credentials" message
• Cannot authenticate even with correct-looking credentials

Possible Causes:

1. Incorrect Client ID or Client Secret
2. Credentials not activated
3. Account suspended or disabled
4. Typo in credentials

Solutions:

1. Verify Credentials: Double-check Client ID and Client Secret for typos
2. Check Account Status: Contact [email protected] to verify account status
3. Test with cURL: Use cURL to isolate the issue:
   Bash

   curl -X POST 'https://api.spreetaileu.com/api/api/v1/auth/login' \
     -H 'Content-Type: application/json' \
     -d '{"client_id": "YOUR_ID", "client_secret": "YOUR_SECRET"}'

4. Check Environment Variables: Ensure environment variables are loaded correctly

Issue: Token expires immediately

Symptoms:

• Token works for a few requests then fails
• Receiving 401 errors shortly after authentication

Possible Causes:

1. Token not being cached properly
2. Multiple instances requesting new tokens
3. Clock skew between client and server

Solutions:

1. Implement Token Caching: Cache tokens and reuse them
2. Check System Clock: Ensure system clock is synchronized
3. Reduce Token Requests: Don't request new token for every API call

Order Creation Issues

Issue: "ReferenceNumber is required" error

Symptoms:

• Receiving 400 error when creating order
• Error message mentions missing ReferenceNumber

Solutions:

1. Check Request Body: Ensure ReferenceNumber field is included
2. Verify JSON Structure: Check that the request is valid JSON
3. Check Field Name: Ensure exact field name (case-sensitive)

# Correct
order = {
    "ReferenceNumber": "ORD-001",  # Correct
    ...
}

# Incorrect
order = {
    "reference_number": "ORD-001",  # Wrong field name
    "referenceNumber": "ORD-001",   # Wrong case
    ...
}

Issue: "Order with ReferenceNumber already exists"

Symptoms:

• Receiving 409 Conflict error
• Error indicates duplicate reference number

Solutions:

1. Check Previous Orders: Verify if order was already created
2. Use Unique Reference Numbers: Implement unique reference number generation
3. Handle Gracefully: If order exists, fetch it instead of creating new one

def create_order_safely(order_data):
    try:
        return create_order(order_data)
    except APIError as e:
        if e.status_code == 409:
            # Order exists, fetch it
            reference = order_data['ReferenceNumber']
            return get_order_by_reference(reference)
        raise

Issue: "Invalid date format" error

Symptoms:

• 400 error with date format message
• Dates not being accepted

Solutions:

1. Use ISO 8601 Format: YYYY-MM-DDTHH:mm:ssZ
2. Use UTC Timezone: Always use UTC (Z suffix)
3. Validate Before Sending: Check date format before API call

from datetime import datetime, timezone

# Correct
date_str = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
# Result: "2025-01-15T10:30:00Z"

# Incorrect formats
"2025-01-15"  # Missing time
"2025-01-15 10:30:00"  # Wrong format
"2025/01/15T10:30:00Z"  # Wrong date separator

Inventory Issues

Issue: SKU not found

Symptoms:

• Empty results when querying inventory
• SKU exists but API returns no results

Possible Causes:

1. SKU doesn't exist in system
2. SKU belongs to different client
3. SKU is inactive or deleted

Solutions:

1. Verify SKU: Check SKU spelling and format
2. Check Client Mapping: Ensure SKU is associated with your client
3. Contact Support: If SKU should exist, contact [email protected]

Issue: Inventory quantity mismatch

Symptoms:

• API shows different quantity than expected
• Quantity doesn't match warehouse system

Solutions:

1. Check Last Updated: Review last_updated timestamp
2. Account for Reserved: Remember quantity = on_hand - reserved
3. Check Timing: Inventory updates may have slight delay
4. Verify Client: Ensure you're checking correct client's inventory

Network and Connection Issues

Issue: Connection timeout

Symptoms:

• Requests timing out
• No response from API

Solutions:

1. Check Network: Verify internet connectivity
2. Increase Timeout: Set appropriate timeout values
3. Retry Logic: Implement retry with exponential backoff
4. Check Firewall: Ensure API domain is not blocked

# Good: Configure timeouts
response = requests.post(
    url,
    json=data,
    timeout=(5, 30)  # (connect timeout, read timeout)
)

Issue: SSL/TLS errors

Symptoms:

• SSL certificate verification errors
• Connection refused errors

Solutions:

1. Update Certificates: Ensure system has latest CA certificates
2. Check API URL: Verify using correct HTTPS URL
3. Update Libraries: Update requests/urllib3 libraries

Rate Limiting Issues

Issue: "Rate limit exceeded" error

Symptoms:

• Receiving 429 Too Many Requests
• Requests being rejected

Solutions:

1. Implement Rate Limiting: Track request rate
2. Use Exponential Backoff: Wait before retrying
3. Batch Requests: Combine multiple operations when possible
4. Request Higher Limits: Contact support for increased limits if needed

# Good: Rate limit handling
if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)
    # Retry request

Debugging Tips

Enable Verbose Logging

import logging
import http.client

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Enable HTTP connection logging
http.client.HTTPConnection.debuglevel = 1

Log Request/Response Details

def log_request_details(request, response):
    logger.debug(f"Request URL: {request.url}")
    logger.debug(f"Request Headers: {dict(request.headers)}")
    logger.debug(f"Request Body: {request.body}")
    logger.debug(f"Response Status: {response.status_code}")
    logger.debug(f"Response Headers: {dict(response.headers)}")
    logger.debug(f"Response Body: {response.text}")

Test with cURL

Use cURL to test API calls directly:

# Test authentication
curl -v -X POST 'https://api.spreetaileu.com/api/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"client_id": "YOUR_ID", "client_secret": "YOUR_SECRET"}'

# Test order creation
curl -v -X POST 'https://api.spreetaileu.com/api/api/v1/outbound' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d @order.json

Validate JSON

Ensure request bodies are valid JSON:

import json

def validate_json(data):
    try:
        json.dumps(data)
        return True
    except (TypeError, ValueError) as e:
        print(f"Invalid JSON: {e}")
        return False

Getting Help

Information to Include

When contacting support, include:

1. Error Message: Exact error message and status code
2. Request Details: Endpoint, method, headers (without tokens)
3. Request Body: Request payload (sanitized)
4. Response: Full response body
5. Timestamp: When the error occurred
6. Client ID: Your client identifier (not secret)
7. Steps to Reproduce: What you did before the error

Contact Support

Email: [email protected]

Subject Format: [API Support] - [Brief Description]

Example:

Subject: [API Support] - 401 Unauthorized when creating order

Body:
Client ID: client-abc-123
Endpoint: POST /outbound
Error: 401 Unauthorized
Error Message: Invalid or expired token
Timestamp: 2025-01-15T10:30:00Z
Steps: Authenticated successfully, then tried to create order immediately

Quick Reference

Status Code Meanings

Common Field Requirements

• ReferenceNumber: Required, unique per client, string
• Currency: Required, ISO 4217 code (EUR, GBP, USD)
• Dates: Required, ISO 8601 format with Z suffix
• OrderItems: Required, array with at least one item
• Addresses: Required, must include FullName, Address1, Town, PostCode, Country

Prevention

Pre-flight Checks

Before making API calls:

1. ✅ Validate all required fields
2. ✅ Check date formats
3. ✅ Verify currency codes
4. ✅ Ensure unique reference numbers
5. ✅ Validate JSON structure
6. ✅ Check authentication token validity
7. ✅ Verify network connectivity

Monitoring

Set up monitoring for:

• Authentication failures
• Error rates by type
• Response times
• Rate limit usage
• Order creation success rate