Skip to main content

​
HTTP Status Codes

StatusMeaningCommon Causes
200SuccessRequest completed successfully
400Bad RequestInvalid parameters or malformed request
401UnauthorizedMissing or invalid API key
402Payment RequiredInsufficient quota for this operation
403ForbiddenValid auth but insufficient permissions
404Not FoundResource doesn’t exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

​
Error Response

When a request fails, the API returns a structured error body alongside the HTTP status code. The error_code field identifies the specific error for programmatic handling: 
{
  "success": false,
  "message": "Human-readable error description",
  "error_code": "ERROR_CODE"
}

​
Error Codes

Error CodeDescription
NOT_FOUNDResource not found
DRIVE_ITEM_CONFLICTDrive item name conflict, e.g. file or folder with the same name already exists
INVALID_ARGUMENTInvalid input: parameter validation, type mismatch, or malformed body
CONNECTOR_NOT_LINKEDThird-party connector (WPS, Lark, etc.) not yet authorized
STATE_NOT_READYResource exists but its current state does not allow the operation
ACCESS_DENIEDCaller lacks permission to access the resource
QUOTA_EXCEEDEDQuota or usage limit exceeded
DOWNLOAD_NOT_SUPPORTEDThe requested resource does not support download
INTERNAL_ERRORUnexpected server-side error

​
Error Handling Best Practices

​
Retry Logic

async function apiRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry 4xx errors (except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`Client error: ${response.status}`);
      }
      
      // Exponential backoff for 5xx and 429
      if (i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

​
Error Logging

try {
  const data = await apiRequest(url, options);
  return data;
} catch (error) {
  console.error('API Error:', {
    url,
    status: error.status,
    message: error.message,
    timestamp: new Date().toISOString()
  });
  throw error;
}

​
Next Steps

Authentication

Learn about authentication

Rate Limits

Understand rate limiting