Error Handling
The API uses standard HTTP status codes and returns structured error responses.
HTTP Status Codes
| Code | Description | |
|---|---|---|
| 200 | Success | |
| 400 | Bad Request — Invalid parameters | |
| 401 | Unauthorized — Missing or invalid token | |
| 403 | Forbidden — Insufficient permissions | |
| 404 | Not Found — Resource doesn't exist | |
| 413 | Payload Too Large — File exceeds storage limit | |
| 429 | Too Many Requests — Quota exceeded | |
| 500 | Server Error — Internal failure |
Error Response Format
json
{
"detail": "Storage limit exceeded. Your plan allows 1024 MB."
}
Common Scenarios
| Scenario | Status | Detail | |
|---|---|---|---|
| Missing auth token | 401 | "Not authenticated" | |
| Invalid API key | 401 | "Invalid API key" | |
| Read quota exceeded | 429 | "API read limit reached" | |
| Write quota exceeded | 429 | "API write limit reached" | |
| Storage full | 413 | "Storage limit exceeded" | |
| File not found | 404 | "Upload not found" | |
| Non-admin route | 403 | "Admin access required" |
Retry Strategy
For 429 responses, implement exponential backoff:
javascript
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const res = await fetch(url, options);
if (res.status !== 429) return res;
const waitMs = Math.pow(2, i) * 1000;
await new Promise(r => setTimeout(r, waitMs));
}
throw new Error("Max retries exceeded");
}