​
Error Response Format

When the Klyra API encounters an error, it returns a JSON response with an error object containing the following properties: 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "type": "authentication_error",
    "param": null,
    "request_id": "req_1a2b3c4d5e6f"
  }
}
  • code: A machine-readable identifier for the error
  • message: A human-readable explanation of what went wrong
  • type: The category of error
  • param: When applicable, the specific parameter that caused the error
  • request_id: A unique identifier for the request, useful when contacting support

​
Authentication Errors

CodeDescriptionResolution
invalid_api_keyAPI key is invalid or has been revokedCheck your API key or generate a new one in the dashboard
missing_api_keyNo API key was providedAdd the Authorization header with your API key
expired_api_keyThe API key has expiredGenerate a new API key in the dashboard
insufficient_permissionsThe API key doesn’t have permission for this actionUse a different API key with the required permissions

​
Request Errors

CodeDescriptionResolution
invalid_requestThe request was malformed or missing required fieldsCheck your request parameters against the API documentation
unsupported_content_typeThe content type provided is not supportedVerify you’re sending a supported content type
content_too_largeThe content exceeds size limitsReduce the size of your content or use chunking for large files
invalid_parametersOne or more parameters are invalidCheck the param field for which parameter is problematic
missing_contentNo content was provided for moderationEnsure the content field in your request is not empty
invalid_urlThe URL provided could not be accessedVerify the URL is correct and publicly accessible

​
Rate Limit Errors

CodeDescriptionResolution
rate_limit_exceededYou’ve exceeded your rate limitWait before retrying or upgrade your plan for higher limits
quota_exceededYou’ve exceeded your monthly quotaUpgrade your plan or wait until the next billing cycle
concurrent_requests_exceededToo many concurrent requestsImplement backoff and limit parallel requests

​
Server Errors

CodeDescriptionResolution
internal_server_errorSomething went wrong on our endContact support with the request_id if this persists
service_unavailableThe service is temporarily unavailableRetry the request after a brief delay
model_unavailableThe requested model is temporarily unavailableTry a different model or retry later
timeoutThe request took too long to processSimplify your request or break it into smaller chunks

​
Content-Specific Errors

CodeDescriptionResolution
unprocessable_contentThe content couldn’t be processedCheck that your content is valid and in a supported format
content_download_failedFailed to download content from the provided URLVerify the URL is publicly accessible and the content exists
unsupported_languageThe language of the content is not supportedCheck the list of supported languages
corrupted_mediaThe media file is corrupted or in an invalid formatVerify the file integrity and format

​
Handling Errors

Here’s an example of how to handle errors in your code: 
try {
  const result = await klyra.moderateText({
    content: "Test content"
  });
  // Process successful response
} catch (error) {
  if (error.error) {
    const { code, message, request_id } = error.error;
    
    switch (code) {
      case 'invalid_api_key':
        console.error('Authentication error:', message);
        // Prompt user to update API key
        break;
      case 'rate_limit_exceeded':
        console.error('Rate limit error:', message);
        // Implement exponential backoff and retry
        break;
      default:
        console.error(`Error (${code}):`, message);
        console.error('Request ID for support:', request_id);
    }
  } else {
    console.error('Network or unknown error:', error);
  }
}

​
Best Practices

  1. Always implement error handling in your integration with the Klyra API
  2. Use exponential backoff when encountering rate limiting errors
  3. Log the request_id for troubleshooting and support
  4. Validate content before sending it to the API
  5. Handle authentication errors by prompting for a new API key
If you encounter persistent errors, contact our support team with the request_id and details about your implementation.