元渊 API元渊 API
Error Handling GuideError Scenarios

Scenario 4: System Errors

Handling system-level errors

Scenario

System-level errors with abnormal response structure.

Response Examples

candidates is null

{
  "candidates": null,
  "error": {
    "code": 500,
    "message": "Internal server error"
  }
}

candidates is empty array

{
  "candidates": [],
  "usageMetadata": { "candidatesTokenCount": 0 }
}

HTTP Status Codes

CodeMeaningRetryable
400Bad RequestNo
401UnauthorizedNo
429Too Many RequestsYes
500Server ErrorYes
503UnavailableYes

Detection

function detectSystemError(response, httpStatus) {
    if (httpStatus !== 200) {
        return { isSystemError: true, httpStatus };
    }
    
    if (!response.candidates || !response.candidates.length) {
        return { isSystemError: true, type: 'NO_CANDIDATES' };
    }
    
    return { isSystemError: false };
}

Retry Strategy

async function retryWithBackoff(fn, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await fn();
        } catch (error) {
            if (attempt === maxRetries - 1) throw error;
            await sleep(Math.pow(2, attempt) * 1000);
        }
    }
}

User Message

⚠️ System Error

Server encountered an error. Please try again.

[Retry automatically in 3s...] [Retry Now]

How is this guide?