DocsTroubleshooting

    Troubleshooting

    Common issues and how to resolve them

    Reference guideAll levels

    Quick Diagnostic

    Before diving in, check these common issues:

    • Are you using the correct API key for your environment (test vs live)?
    • Is your API key active and not expired?
    • Are all required headers included in your request?
    • Is your request body properly formatted as JSON?

    HTTP Error Codes

    400Bad Request

    The request was malformed or contains invalid parameters.

    Common Causes:

    • Missing required fields
    • Invalid data format
    • Validation errors

    Solution

    Check the request body and ensure all required fields are present with valid values.

    401Unauthorized

    Authentication failed or API key is invalid.

    Common Causes:

    • Missing API key
    • Invalid API key
    • Expired API key
    • Wrong environment key

    Solution

    Verify your API key is correct and matches the environment (test/live). Check the Authorization header format.

    403Forbidden

    You don't have permission to access this resource.

    Common Causes:

    • Insufficient permissions
    • Resource belongs to another tenant
    • Feature not available on your plan

    Solution

    Check your account permissions and ensure you're accessing resources within your tenant.

    404Not Found

    The requested resource doesn't exist.

    Common Causes:

    • Invalid resource ID
    • Resource was deleted
    • Typo in endpoint URL

    Solution

    Verify the resource ID exists and the endpoint URL is correct.

    429Rate Limited

    You've exceeded the rate limit for API requests.

    Common Causes:

    • Too many requests in a short period
    • Burst of requests without throttling

    Solution

    Implement exponential backoff and respect the Retry-After header. Consider caching frequently accessed data.

    500Internal Server Error

    An unexpected error occurred on our servers.

    Common Causes:

    • Temporary server issue
    • Bug in our system

    Solution

    Retry the request after a short delay. If the issue persists, contact support with the request ID.

    Common Issues

    Points are not being awarded after a transaction
    This can happen for several reasons: 1. **Check the transaction amount** - Ensure the purchase amount meets the minimum threshold for earning points. 2. **Verify the customer exists** - Make sure the customer_id in your request is valid. 3. **Check your earn rules** - Verify your loyalty program's earn rules are configured correctly in the dashboard. 4. **Look for validation errors** - Check the API response for any validation errors. 5. **Confirm the program is active** - Ensure your loyalty program is not paused or expired.
    Webhooks are not being received
    Common causes and solutions: 1. **Verify your endpoint URL** - Ensure the URL is correct and publicly accessible. 2. **Check HTTPS** - Webhooks only work with HTTPS endpoints in production. 3. **Review firewall settings** - Make sure your server allows incoming requests from LoyalPro IPs. 4. **Check the webhook logs** - View delivery attempts in your dashboard under Developers → Webhooks. 5. **Verify event subscription** - Ensure you've subscribed to the specific events you want to receive.
    Customer lookup returns 'not found' but customer exists
    This usually indicates one of these issues: 1. **Wrong environment** - You might be using test API keys to look up a live customer, or vice versa. 2. **Wrong tenant** - In multi-tenant setups, ensure you're querying within the correct tenant context. 3. **Deleted customer** - The customer may have been soft-deleted. Check with include_deleted=true parameter. 4. **Typo in customer ID** - Double-check the customer ID format and value.
    API requests are slow
    To improve API performance: 1. **Implement caching** - Cache frequently accessed data like customer profiles. 2. **Use pagination** - Don't fetch all records at once. Use cursor-based pagination. 3. **Minimize payload size** - Use field selection to request only the data you need. 4. **Check your network** - Test from a server closer to our API endpoints. 5. **Batch operations** - Use bulk endpoints when available for multiple operations.
    Redemption fails with 'insufficient balance'
    Check these common causes: 1. **Points haven't posted yet** - There may be a pending period before points are available. 2. **Points have expired** - Check if the customer's points have an expiration date. 3. **Already redeemed** - The points may have been redeemed in another transaction. 4. **Calculation mismatch** - Your local balance calculation may be out of sync with the server.

    Debugging Tips

    Use these techniques to identify and resolve issues quickly:

    1

    Check the response headers

    Every API response includes a X-Request-ID header. Include this when contacting support.

    2

    Use verbose logging

    Enable request/response logging in your SDK to see the full API communication.

    3

    Test in isolation

    Use cURL or Postman to test API calls independently from your application code.

    4

    Verify webhook payloads

    Use webhook.site or ngrok to inspect incoming webhook payloads during development.

    5

    Check the API status page

    Visit our status page to check for any ongoing incidents that might affect your integration.

    Debug Request with cURL
    curl -X GET "https://api.loyalpro.com/v1/customers/cus_abc123" \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -v

    Getting Support

    Still stuck?

    Our developer support team is ready to help. When contacting support, please include:

    • Your Request ID (from X-Request-ID header)
    • The full error message
    • Steps to reproduce the issue
    • Your SDK version

    Was this page helpful?

    Help us improve our documentation