HTTP Status Codes
| Status | Meaning | Common Causes |
|---|---|---|
| 200 | Success | Request completed successfully |
| 400 | Bad Request | Invalid parameters or malformed request |
| 401 | Unauthorized | Missing or invalid API key |
| 402 | Payment Required | Insufficient quota for this operation |
| 403 | Forbidden | Valid auth but insufficient permissions |
| 404 | Not Found | Resource doesn’t exist |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server-side error |
Error Response
When a request fails, the API returns a structured error body alongside the HTTP status code. Theerror_code field identifies the specific error for programmatic handling:
{
"success": false,
"message": "Human-readable error description",
"error_code": "ERROR_CODE"
}
Error Codes
| Error Code | Description |
|---|---|
NOT_FOUND | Resource not found |
DRIVE_ITEM_CONFLICT | Drive item name conflict, e.g. file or folder with the same name already exists |
INVALID_ARGUMENT | Invalid input: parameter validation, type mismatch, or malformed body |
CONNECTOR_NOT_LINKED | Third-party connector (WPS, Lark, etc.) not yet authorized |
STATE_NOT_READY | Resource exists but its current state does not allow the operation |
ACCESS_DENIED | Caller lacks permission to access the resource |
QUOTA_EXCEEDED | Quota or usage limit exceeded |
DATASET_TABLE_LIMIT_EXCEEDED | Number of tables in the NL2SQL dataset exceeds the allowed limit |
DOWNLOAD_NOT_SUPPORTED | The requested resource does not support download |
UNAUTHORIZE | Authentication required |
CONNECTOR_UNAUTHORIZE | Connector unauthorized |
CUSTOM_ID_CONFLICT | A resource with the given custom_id already exists |
BINDING_ALREADY_EXISTS | The binding relationship already exists |
INTERNAL_ERROR | Unexpected 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