Troubleshooting Guide

This guide helps you resolve common issues when working with the XD Soba API.

Common Issues

Authentication Errors

401 Unauthorized

• Check if your token is valid and not expired
• Verify the token format: Bearer your_token_here
• Ensure you're using the correct credentials

403 Forbidden

• Verify your account has the necessary permissions
• Check if your API key is active
• Contact support if you need access to specific endpoints

Resource Errors

404 Not Found

• Verify the endpoint URL is correct
• Check if the resource ID exists
• Ensure the resource has not been deleted

Rate Limiting

429 Too Many Requests

• Check the rate limit headers in the response
• Implement exponential backoff in your retry logic
• Consider implementing caching to reduce API calls

Validation Errors

400 Bad Request

• Verify all required fields are present
• Check data types and formats
• Ensure date formats are correct (ISO 8601)
• Validate string lengths and numeric ranges

Server Errors

500 Internal Server Error

• This is a server-side error — retry the request after a few seconds
• If the error persists, contact support
• Include the X-Request-ID header value when reporting the issue

Error Codes

Code	Description	Solution
Entity.Duplicated	An entity with this code already exists.	Verify the entity code and use a unique value
Entity.IsNotASupplier	The required entity is not a supplier	Ensure the selected entity is of type supplier
Item.CanNotChangeSerialNumberType	You cannot change the serial number type as the item already has documents associated with it.	The item already has associated documents, so this change is not allowed
Item.InvalidPrinterNumber	Printer number must be between 1 and 20.	Ensure the printer number is within the valid range (1 to 20)
ItemStock.NotFound	Item stock record not found.	Verify that the item has a registered stock record
PointsConfig.InvalidDateRange	The start date cannot be greater than the end date.	Ensure the start date is earlier than or equal to the end date
Resource.ExceededFileSize	The file size exceeded the allowed limit.	Reduce the file size to be within the allowed limit

Debugging Tips

Request Logging

Enable request logging in your application:

// C# example
var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Debug", "true");

Response Headers

Check these headers for additional information:

• X-Request-ID: For tracking requests
• X-RateLimit-*: For rate limit information
• X-Error-Code: For detailed error codes

Common Solutions

1. Token Issues

   # Verify token format
   curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Authorization: Bearer your_token_here" \
        -v

2. Rate Limiting

   # Check rate limit headers
   curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Authorization: Bearer your_token_here" \
        -I

3. Validation Errors

   # Test with minimal payload
   curl -X POST "https://api.xdsoba.com/gateway/your-endpoint" \
        -H "Content-Type: application/json" \
        -d '{"required_field": "value"}'

Getting Help

If you're still experiencing issues:

1. Check Documentation
   • Review the Getting Started Guide
   • Read the API Usage Guide
   • Check the API Reference