Skip to main content
Keymint uses standard HTTP status codes combined with custom error codes to provide detailed error information for better debugging and error handling.

​
Error Response Structure

All error responses follow this consistent structure: 
{
  "message": "Descriptive error message",
  "code": 1
}
  • Success Response
  • Error Response
{
  "message": "License activated successfully",
  "code": 0,
  "data": {
    // Response data
  }
}

​
Complete Error Code Reference

HTTP StatusCodeDescription
200 OK0Success - Request completed successfully
HTTP StatusCodeDescriptionCommon Causes
400 Bad Request1Malformed Request - Missing or invalid parametersMissing productId, licenseKey, invalid date format
401 Unauthorized1Invalid Token - Authentication failedMissing, expired, or invalid access token
403 Forbidden2Operation Restricted - License state prevents actionExpired license, activation limit reached, blocked
404 Not Found1Resource Not Found - Requested resource doesn’t existInvalid productId, licenseKey, customerId
404 Not Found2Customer Not Found - Specific to customer operationsCustomer ID doesn’t exist
409 Conflict2Resource Conflict - State prevents requestDuplicate customer email, existing activation
429 Too Many Requests3Rate Limit Exceeded - Too many requestsExceeded API rate limits
HTTP StatusCodeDescriptionAction Required
500 Internal Server Error1Server Error - Unexpected server issueContact support if persistent

​
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).

​
Error Handling Best Practices

Parse Error Codes

Always check both HTTP status and custom error code for complete error context.

Implement Retry Logic

Use exponential backoff for rate limit errors (code 3) and temporary server errors.

Log Error Details

Log both the error message and code for debugging and monitoring purposes.

User-Friendly Messages

Translate technical error messages into user-friendly notifications.

​
Error Handling Examples

  • JavaScript
  • Python
async function handleApiCall(apiFunction) {
  try {
    const response = await apiFunction();
    return response;
  } catch (error) {
    switch (error.status) {
      case 400:
        console.error('Bad Request:', error.data.message);
        // Handle validation errors
        break;
      case 401:
        console.error('Unauthorized:', error.data.message);
        // Refresh token or redirect to login
        break;
      case 403:
        console.error('Forbidden:', error.data.message);
        // Handle license restrictions
        break;
      case 404:
        console.error('Not Found:', error.data.message);
        // Handle missing resources
        break;
      case 429:
        console.error('Rate Limited:', error.data.message);
        // Implement exponential backoff
        await retryWithBackoff(apiFunction);
        break;
      case 500:
        console.error('Server Error:', error.data.message);
        // Log for monitoring, show user-friendly message
        break;
      default:
        console.error('Unexpected Error:', error);
    }
    throw error;
  }
}
Always implement proper error handling in production applications. Never expose raw API error messages to end users without proper sanitization.
⌘I