Skip to main content

Error Codes

This document provides a comprehensive reference for all error codes returned by the Cloakr.ai API.

Error Response Format​

All API errors follow a consistent format:

{
  "error": {
    "type": "error_type",
    "message": "Human-readable error message",
    "code": "machine_readable_code",
    "param": "parameter_name", // Optional
    "retry_after": 60, // Optional, seconds
    "details": {} // Optional, additional context
  }
}

HTTP Status Codes​

Status CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error
502Bad Gateway - Upstream service error
503Service Unavailable - Service temporarily unavailable

Authentication Errors​

401 Unauthorized​

invalid_api_key​

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key"
  }
}

Resolution: Check your API key in the Cloakr Dashboard and ensure it's correctly set in your environment variables.

api_key_expired​

{
  "error": {
    "type": "authentication_error",
    "message": "API key has expired",
    "code": "api_key_expired"
  }
}

Resolution: Generate a new API key from the dashboard.

insufficient_permissions​

{
  "error": {
    "type": "authentication_error",
    "message": "API key lacks required permissions",
    "code": "insufficient_permissions",
    "details": {
      "required_permissions": ["chat:write", "models:read"]
    }
  }
}

Resolution: Contact your administrator to grant the required permissions.

Rate Limiting Errors​

429 Too Many Requests​

rate_limit_exceeded​

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded",
    "code": "rate_limit_exceeded",
    "retry_after": 60
  }
}

Resolution: Wait for the specified time before retrying, or upgrade your plan for higher limits.

quota_exceeded​

{
  "error": {
    "type": "rate_limit_error",
    "message": "Monthly quota exceeded",
    "code": "quota_exceeded"
  }
}

Resolution: Upgrade your plan or wait for the next billing cycle.

Request Validation Errors​

400 Bad Request​

invalid_model​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid model specified",
    "code": "invalid_model",
    "param": "model"
  }
}

Resolution: Use the Models endpoint to get a list of available models.

invalid_prompt​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Prompt cannot be empty",
    "code": "invalid_prompt",
    "param": "prompt"
  }
}

Resolution: Ensure the prompt field is not empty and contains valid text.

invalid_temperature​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Temperature must be between 0 and 2",
    "code": "invalid_temperature",
    "param": "temperature"
  }
}

Resolution: Set temperature to a value between 0.0 and 2.0.

invalid_max_tokens​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Max tokens exceeds model limit",
    "code": "invalid_max_tokens",
    "param": "max_tokens",
    "details": {
      "model_limit": 128000,
      "requested": 150000
    }
  }
}

Resolution: Reduce max_tokens to within the model's limit.

invalid_encryption​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid encryption format",
    "code": "invalid_encryption",
    "param": "prompt"
  }
}

Resolution: Ensure encrypted prompts use the correct AES-256-GCM format.

Content Policy Errors​

400 Bad Request​

content_policy_violation​

{
  "error": {
    "type": "content_policy_error",
    "message": "Content violates usage policies",
    "code": "content_policy_violation",
    "details": {
      "violation_type": "harmful_content",
      "flagged_content": "specific text that was flagged"
    }
  }
}

Resolution: Review and modify your prompt to comply with our content policies.

pii_detection_failed​

{
  "error": {
    "type": "content_policy_error",
    "message": "PII detection failed",
    "code": "pii_detection_failed",
    "details": {
      "detected_pii": ["email", "phone_number"],
      "redaction_required": true
    }
  }
}

Resolution: Remove or redact the detected PII before sending the request.

Server Errors​

500 Internal Server Error​

internal_error​

{
  "error": {
    "type": "server_error",
    "message": "An internal error occurred",
    "code": "internal_error"
  }
}

Resolution: Retry the request. If the error persists, contact support.

model_unavailable​

{
  "error": {
    "type": "server_error",
    "message": "Model is temporarily unavailable",
    "code": "model_unavailable",
    "param": "model"
  }
}

Resolution: Try a different model or retry later.

502 Bad Gateway​

upstream_error​

{
  "error": {
    "type": "server_error",
    "message": "Upstream service error",
    "code": "upstream_error",
    "details": {
      "upstream_service": "openai",
      "upstream_error": "service_unavailable"
    }
  }
}

Resolution: Retry the request. The error is temporary.

503 Service Unavailable​

maintenance_mode​

{
  "error": {
    "type": "server_error",
    "message": "Service is under maintenance",
    "code": "maintenance_mode",
    "retry_after": 3600
  }
}

Resolution: Wait for maintenance to complete and retry.

SDK-Specific Errors​

Encryption Errors​

encryption_failed​

{
  "error": {
    "type": "encryption_error",
    "message": "Failed to encrypt request",
    "code": "encryption_failed",
    "details": {
      "reason": "invalid_key_format"
    }
  }
}

Resolution: Check your encryption key format and ensure it's properly configured.

decryption_failed​

{
  "error": {
    "type": "encryption_error",
    "message": "Failed to decrypt response",
    "code": "decryption_failed"
  }
}

Resolution: Ensure your encryption keys are synchronized between client and server.

Error Handling Best Practices​

1. Implement Retry Logic​

async function makeRequestWithRetry(client, request, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await client.chat(request);
    } catch (error) {
      if (error.code === 'rate_limit_exceeded') {
        const retryAfter = error.retry_after || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      if (error.code === 'internal_error' && attempt < maxRetries) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
        continue;
      }
      
      throw error;
    }
  }
}

2. Handle Rate Limits​

async function handleRateLimit(error) {
  if (error.code === 'rate_limit_exceeded') {
    const retryAfter = error.retry_after || 60;
    console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return true; // Retry the request
  }
  return false; // Don't retry
}

3. Validate Requests​

function validateChatRequest(request) {
  const errors = [];
  
  if (!request.model) {
    errors.push('model is required');
  }
  
  if (!request.prompt) {
    errors.push('prompt is required');
  }
  
  if (request.temperature && (request.temperature < 0 || request.temperature > 2)) {
    errors.push('temperature must be between 0 and 2');
  }
  
  return errors;
}

4. Log Errors Appropriately​

function logError(error, context) {
  console.error('Cloakr API Error:', {
    code: error.code,
    message: error.message,
    type: error.type,
    context: context,
    timestamp: new Date().toISOString()
  });
}

Getting Help​

If you encounter an error not covered in this documentation:

  1. Check the error code and message for specific guidance
  2. Review your request for common issues
  3. Contact support at support@cloakr.ai with:
    • Error code and message
    • Request details (without sensitive data)
    • SDK version and language
    • Steps to reproduce

Next Steps​