API Error Codes & Handling
Elept uses standard HTTP status codes combined with machine-readable JSON error objects. Errors always include an error code and a human-readable explanation, with internal server paths and debug traces suppressed in production.
Standard Error Format
{
"error": true,
"code": "quota_exceeded",
"message": "Workspace storage limit exceeded."
}
HTTP Status Codes
| Status | Code | Description |
|---|---|---|
| 400 | invalid_params / invalid_account |
Malformed JSON syntax, missing required fields, or missing workspace account ID. |
| 401 | unauthorized |
Missing, invalid, or revoked Bearer API token. |
| 403 | forbidden_scope |
API key lacks permissions (e.g. read-only key attempting upload or delete), or signed URL has expired/tampered signature. |
| 404 | file_not_found / route_not_found |
Requested file UID, collection room, or space does not exist, or the requested API route URL was not found. |
| 413 | quota_exceeded / file_too_large |
Payload exceeds workspace account storage limits, per-file limits, or server POST limits. |
| 415 | blocked_file_type |
Disallowed executable file extension (e.g. .php, .exe, .sh) or MIME type rejected by security policy. |
| 422 | validation_error |
Unprocessable entity, such as empty uploaded files or invalid parameters. |
| 429 | rate_limit_exceeded |
Too many requests. Check the Retry-After header before resubmitting. |
| 502 / 503 | storage_unavailable |
Downstream cloud storage provider temporary communication issue. Safe to retry with exponential backoff. |
Handling Recommendations
- Client retries: Automatically retry on 502, 503, or 429 status codes using exponential backoff with jitter.
- Permanent failures: Do not retry 400, 401, 403, 404, 413, or 415 responses without correcting the underlying payload or credentials.
- Signed URLs: Check the
expirestimestamp parameter before serving URLs to end-users to ensure they have not expired.