Error Codes

The Keymint API employs a structured error-handling approach, combining standard HTTP status codes with custom error codes. This ensures clear and actionable insights for developers. Below is a detailed breakdown of the error responses:

---

Error Code Reference

HTTP Status Code	Error Code (code)	Description	Example Response Body	Possible Causes / Notes
200 OK	0	Success: The request was successful. The operation (get, activate, create, block, unblock) completed.	{"message": "License valid", "code": 0} (varies by endpoint)	Indicates successful execution. The message field provides context.
400 Bad Request	1	Malformed Request: Missing or invalid parameters in the request body or query string.	{"message": "Missing required params", "code": 1}	Ensure all required fields (productId, licenseKey, accessToken, etc.) are present and correctly formatted (e.g., expiryDate).
401 Unauthorized	1	Invalid Token: The accessToken is missing, invalid, expired, or lacks proper authorization for the product.	{"message": "Invalid access token", "code": 1}	Verify the token is valid, not expired, and has permissions for the specified productId (or is a global token).
403 Forbidden	2	Operation Restricted: The license or related resource prevents the operation.	{"message": "License expired", "code": 2}	Examples: License expired, activation limit reached, license already inactive (when trying to deactivate), customer inactive, license blocked.
404 Not Found	1 or 2	Resource Not Found: A specified resource (product, license key, customer, device) could not be found.	{"message": "Invalid license key", "code": 1} {"message": "Device not found", "code": 1} {"message": "Customer ... not found", "code": 2}	Verify identifiers (productId, licenseKey, hostId, customerId). code: 1 is general; code: 2 specifically for "Customer not found" in create.
409 Conflict	2	Resource Conflict: The request could not be completed due to a conflict with the current state of the resource.	{"message": "CONFLICT: Customer email ... already exists.", "code": 2}	Used when creating a customer (/create-key) if the provided email already exists.
429 Too Many Requests	3	Rate Limit Exceeded: Too many requests within a given timeframe.	{"message": "Too many activation attempts. Please try again later.", "code": 3}	Implement exponential backoff or retry after a cooldown period. Applies primarily to activation/validation endpoints.
500 Internal Server Error	1	Server Error: An unexpected error occurred on the server side (e.g., database issue, code bug).	{"message": "Server error", "code": 1}	May include more specific messages (e.g., "DB_INSERT_FAIL"). Contact support if the issue persists.

---

Additional Notes

Error Code Context

• Some error codes (like 1 and 2) are reused across different HTTP statuses.
• The HTTP status code provides the primary classification (e.g., Bad Request, Unauthorized).
• The message field offers specific details about the error.

Rate Limiting (429)

• Implement robust retry logic, preferably with exponential backoff, when encountering this status.

Server Errors (500)

• These usually indicate a problem beyond the client's control.
• Log the error and notify support if the issue persists.

code Field

• This custom code provides a secondary level of detail, differentiating between types of errors within the same HTTP status (e.g., 404 with code: 1 vs code: 2).

By understanding these error codes and their meanings, developers can implement robust error handling and improve the resilience of their applications interacting with the Keymint API.