Errors and Troubleshooting

This section provides a comprehensive guide to understanding and resolving errors that may occur while using the Humance SDK and API. By leveraging the detailed error response objects and following the best practices outlined here, you can efficiently debug and troubleshoot integration issues.

---

HTTP Status Codes and Error Handling

The Humance API uses standard HTTP status codes to indicate whether a request was successful or encountered an issue. All successful requests return 200 OK, while errors return codes other than 200.

HTTP Status Code Summary

Code	Status	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid, but the request failed.
403	Forbidden	The API key doesn't have permission to perform the request.
404	Not Found	The requested resource doesn't exist.
409	Conflict	The request conflicts with another request (e.g., duplicate idempotent key).
422	Validation Error	Errors related to transferred parameters.
429	Too Many Requests	Too many requests sent in a short time. Use exponential backoff.

---

Error Response Object

When an error occurs, the Humance API returns a detailed error response object, making it easier to identify and resolve issues.

Example Error Response:

{
    "message": "This action is unauthorized.",  // Description of the error
    "code": 40300,                              // Error code
    "fix": "You don't have access to the resource", // Suggested solution
    "params": {                                 // Errors related to specific parameters
        "parameter_1": [
            "Error message 1",
            "Error message 2"
        ],
        "parameter_2": [
            "Error message 1",
            "Error message 2"
        ]
    }
}

---

Troubleshooting Steps

1. Validate API Requests:

   • Ensure all required parameters are included in the API request.

   • Double-check the request format (e.g., headers, query strings, and body).

2. Check API Keys:

   • Verify that the correct API keys are being used for the current environment (test or production).

   • Ensure the keys are valid and authorized for the requested operation.

3. Handle Rate Limiting:

   • If you encounter 429 Too Many Requests, implement exponential backoff to retry requests after a delay.

4. Debugging Parameter Errors:

   • Refer to the params field in the error response for details about which parameters caused the issue.

   • Example: If parameter_1 shows multiple errors, ensure the provided value meets the API requirements.

5. Verify SDK Configuration:

   • Confirm that the SDK is properly configured with valid apiConfig fields, including:

     • userEmail

     • apiKey

     • apiSecret

     • allowPersonalization

6. Simulate Common Errors:

   • Test your app’s error-handling logic by intentionally triggering errors, such as:

     • Sending an invalid API key.

     • Omitting required parameters.

     • Using an unsupported HTTP method.

---

Common Issues and Fixes

Issue	Cause	Fix
401 Unauthorized	Invalid or missing API key	Verify that the correct API key and secret are included in the request headers.
400 Bad Request	Missing required parameter	Ensure all required parameters are present and properly formatted.
403 Forbidden	API key lacks required permissions	Check your Humance account settings and ensure the key has access to the requested API.
422 Validation Error	Incorrect parameter value	Review the params field in the error response for guidance on fixing the input data.
429 Too Many Requests	Rate-limiting triggered	Implement exponential backoff and retry the request after a delay.
404 Not Found	Requested resource does not exist	Verify the resource ID or URL used in the request.