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
| Code | Meaning | Retryable |
|---|---|---|
| 400 | Bad Request | No |
| 401 | Unauthorized | No |
| 429 | Too Many Requests | Yes |
| 500 | Server Error | Yes |
| 503 | Unavailable | Yes |
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]Related Docs
How is this guide?