Back to Details

juicebox-common-errors

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Juicebox Common Errors

Juicebox 常见错误

Overview

概述

Quick reference for diagnosing and resolving common Juicebox API errors.
用于诊断和解决Juicebox API常见错误的快速参考指南。

Error Reference

错误参考

Authentication Errors

认证错误

401 Unauthorized

401 Unauthorized

Error: Invalid or expired API key
Code: AUTHENTICATION_FAILED
Causes:
  • API key is incorrect
  • API key has been revoked
  • Environment variable not set
Solutions:
bash
undefined
Error: Invalid or expired API key
Code: AUTHENTICATION_FAILED
原因：
  • API key 不正确
  • API key 已被撤销
  • 环境变量未设置
解决方案：
bash
undefined

Verify API key is set

Verify API key is set

echo $JUICEBOX_API_KEY
echo $JUICEBOX_API_KEY

Test with curl

Test with curl

curl -H "Authorization: Bearer $JUICEBOX_API_KEY"
https://api.juicebox.ai/v1/auth/verify
undefined
curl -H "Authorization: Bearer $JUICEBOX_API_KEY"
https://api.juicebox.ai/v1/auth/verify
undefined

403 Forbidden

403 Forbidden

Error: Insufficient permissions for this operation
Code: PERMISSION_DENIED
Causes:
  • API key lacks required scope
  • Account tier limitation
  • Feature not available in plan
Solutions:
  • Check API key permissions in dashboard
  • Upgrade account tier if needed
  • Contact support for access
Error: Insufficient permissions for this operation
Code: PERMISSION_DENIED
原因：
  • API key 缺少所需权限范围
  • 账户层级限制
  • 套餐中未包含该功能
解决方案：
  • 在控制台中检查API key的权限
  • 如有需要，升级账户层级
  • 联系支持团队申请访问权限

Rate Limiting Errors

限流错误

429 Too Many Requests

429 Too Many Requests

Error: Rate limit exceeded
Code: RATE_LIMITED
Retry-After: 60
Causes:
  • Exceeded requests per minute
  • Exceeded daily quota
  • Burst limit hit
Solutions:
typescript
// Implement exponential backoff
async function withBackoff(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMITED') {
        const delay = error.retryAfter * 1000 || Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}
Error: Rate limit exceeded
Code: RATE_LIMITED
Retry-After: 60
原因：
  • 超出每分钟请求次数限制
  • 超出每日配额
  • 达到突发请求限制
解决方案：
typescript
// Implement exponential backoff
async function withBackoff(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMITED') {
        const delay = error.retryAfter * 1000 || Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

Search Errors

搜索错误

400 Bad Request - Invalid Query

400 Bad Request - Invalid Query

Error: Invalid search query syntax
Code: INVALID_QUERY
Details: Unexpected token at position 15
Causes:
  • Malformed query syntax
  • Invalid field name
  • Unclosed quotes
Solutions:
typescript
// Validate query before sending
function validateQuery(query: string): boolean {
  const openQuotes = (query.match(/"/g) || []).length;
  if (openQuotes % 2 !== 0) return false;

  const openParens = (query.match(/\(/g) || []).length;
  const closeParens = (query.match(/\)/g) || []).length;
  if (openParens !== closeParens) return false;

  return true;
}
Error: Invalid search query syntax
Code: INVALID_QUERY
Details: Unexpected token at position 15
原因：
  • 查询语法格式错误
  • 字段名称无效
  • 引号未闭合
解决方案：
typescript
// Validate query before sending
function validateQuery(query: string): boolean {
  const openQuotes = (query.match(/"/g) || []).length;
  if (openQuotes % 2 !== 0) return false;

  const openParens = (query.match(/\(/g) || []).length;
  const closeParens = (query.match(/\)/g) || []).length;
  if (openParens !== closeParens) return false;

  return true;
}

404 Profile Not Found

404 Profile Not Found

Error: Profile with ID 'xxx' not found
Code: NOT_FOUND
Causes:
  • Profile ID is invalid
  • Profile has been removed
  • Stale cache reference
Solutions:
  • Verify profile ID format
  • Handle not found gracefully
  • Implement cache invalidation
Error: Profile with ID 'xxx' not found
Code: NOT_FOUND
原因：
  • 配置文件ID无效
  • 配置文件已被移除
  • 缓存引用过期
解决方案：
  • 验证配置文件ID格式
  • 优雅处理未找到的情况
  • 实现缓存失效机制

Network Errors

网络错误

ETIMEDOUT

ETIMEDOUT

Error: Request timed out
Code: TIMEOUT
Solutions:
typescript
// Increase timeout for large searches
const client = new JuiceboxClient({
  apiKey: process.env.JUICEBOX_API_KEY,
  timeout: 60000 // 60 seconds
});
Error: Request timed out
Code: TIMEOUT
解决方案：
typescript
// Increase timeout for large searches
const client = new JuiceboxClient({
  apiKey: process.env.JUICEBOX_API_KEY,
  timeout: 60000 // 60 seconds
});

Diagnostic Commands

诊断命令

bash
undefined
bash
undefined

Check API status

Check API status

curl https://status.juicebox.ai/api/status
curl https://status.juicebox.ai/api/status

Verify connectivity

Verify connectivity

curl -I https://api.juicebox.ai/v1/health
curl -I https://api.juicebox.ai/v1/health

Test authentication

Test authentication

curl -H "Authorization: Bearer $JUICEBOX_API_KEY"
https://api.juicebox.ai/v1/auth/me
undefined
curl -H "Authorization: Bearer $JUICEBOX_API_KEY"
https://api.juicebox.ai/v1/auth/me
undefined

Error Handling Pattern

错误处理模式

typescript
try {
  const results = await juicebox.search.people(query);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Queue for retry
  } else if (error.code === 'INVALID_QUERY') {
    // Fix query syntax
  } else if (error.code === 'AUTHENTICATION_FAILED') {
    // Refresh credentials
  } else {
    // Log and alert
    logger.error('Juicebox error', { error });
  }
}
typescript
try {
  const results = await juicebox.search.people(query);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Queue for retry
  } else if (error.code === 'INVALID_QUERY') {
    // Fix query syntax
  } else if (error.code === 'AUTHENTICATION_FAILED') {
    // Refresh credentials
  } else {
    // Log and alert
    logger.error('Juicebox error', { error });
  }
}

Resources

相关资源

Next Steps

后续步骤

After resolving errors, see 
juicebox-debug-bundle
for collecting diagnostic info.
解决错误后，可使用
juicebox-debug-bundle
收集诊断信息。