Error Codes

Response Structure

Success:

json

{
  "code": 0,
  "data": { ... }
}

Error:

json

{
  "message": "Descriptive error message",
  "code": 1
}

The code field differentiates error types within the same HTTP status.

Error Code Reference

Success

HTTP	Code	Description
200	0	Request completed successfully

Client Errors

HTTP	Code	Description
400	1	Missing or invalid parameters
401	1	Invalid or missing API key
403	2	License expired, blocked, or activation limit reached
403	3	Unauthorized device — `hostId` not in `allowedHosts`
404	1	Resource not found (product, license key, or customer)
409	2	Conflict — duplicate email or existing resource
429	1	Rate limit exceeded

Server Errors

HTTP	Code	Description
500	1	Unexpected server error — contact support if persistent

Handling Errors

javascript

const res = await fetch('https://api.keymint.dev/key/activate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ productId, licenseKey, hostId })
});

const data = await res.json();

if (!res.ok) {
  switch (res.status) {
    case 401: // Re-authenticate or check API key
    case 403: // License restricted — check data.code for specifics
    case 404: // Invalid product or key
    case 429: // Back off and retry
      break;
  }
}

Never expose raw API error messages to end users. Map them to user-friendly messages in your application.