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:

Check the response headers

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

Use verbose logging

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

Test in isolation

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

Verify webhook payloads

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

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

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

Webhooks are not being received

Customer lookup returns 'not found' but customer exists

API requests are slow

Redemption fails with 'insufficient balance'

Debugging Tips

Use these techniques to identify and resolve issues quickly:

Check the response headers

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

Use verbose logging

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

Test in isolation

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

Verify webhook payloads

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

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

Troubleshooting

Quick Diagnostic

HTTP Error Codes

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Issues

Debugging Tips

Check the response headers

Use verbose logging

Test in isolation

Verify webhook payloads

Check the API status page

Getting Support

Still stuck?

Was this page helpful?

Troubleshooting

Quick Diagnostic

HTTP Error Codes

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Causes:

Solution

Common Issues

Debugging Tips

Check the response headers

Use verbose logging

Test in isolation

Verify webhook payloads

Check the API status page

Getting Support

Still stuck?

Was this page helpful?