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
}

{
  "message": "License activated successfully",
  "code": 0,
  "data": {
    // Response data
  }
}

​
Complete Error Code Reference

​
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

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.