Insufficient Storage
ActiveHTTP 507 Insufficient Storage indicates the server cannot store the representation needed to complete the request. Defined in RFC 4918 §11.5 (WebDAV). The server's storage is full — distinct from 413 where the request body is too large. Common in cloud storage, email, and file hosting services.
Description
The 507 Insufficient Storage status code means the method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. The server's available storage has been exhausted — whether that's disk space, a user quota, a database limit, or an object store capacity ceiling.
This is fundamentally different from 413 Content Too Large. With 413, the problem is the client's request body — it's sending too much data in a single payload. With 507, the request size may be perfectly reasonable, but the server simply has nowhere to put it. A 1KB file upload can trigger 507 if the server's disk is full. A 100MB upload can succeed with 200 if there's plenty of space. The constraint is on the server side, not the request side.
Originally defined in RFC 4918 for WebDAV, where users upload and manage files on remote servers. When a user's quota is exhausted or the server partition is full, 507 communicates this clearly. The status has since been adopted by cloud storage APIs, email servers (mailbox full), content management systems, and any service where server-side storage is a finite, exhaustible resource.
Because storage exhaustion is often temporary — quotas reset monthly, administrators add capacity, users delete old files — servers SHOULD include a Retry-After header when the condition is expected to resolve. The response body should indicate what limit was hit and how the client can resolve it (upgrade plan, delete files, contact admin).
Some modern REST APIs extend 507 beyond filesystem storage to cover database row limits, blob storage quotas, and even in-memory cache capacity. While purists may debate whether this stretches the original WebDAV intent, the semantic — 'server cannot store what you need it to store' — maps cleanly to these scenarios.
Examples
PUT /webdav/documents/report-2024.pdf HTTP/1.1
Host: files.example.com
Content-Type: application/pdf
Content-Length: 5242880
Authorization: Bearer token123
[5MB PDF binary data]HTTP/1.1 507 Insufficient Storage
Content-Type: application/json
Retry-After: 86400
{"error": "insufficient_storage", "message": "Your storage quota has been exceeded. Used: 5.0 GB / 5.0 GB. Please delete files or upgrade your plan.", "quota_used": 5368709120, "quota_limit": 5368709120, "upgrade_url": "/account/plans"}POST /api/mail/deliver HTTP/1.1
Host: mail.example.com
Content-Type: application/json
{"to": "user@example.com", "subject": "Monthly Report", "body": "...", "attachments": [{"name": "data.csv", "size": 2048000}]}HTTP/1.1 507 Insufficient Storage
Content-Type: application/json
Retry-After: 3600
{"error": "mailbox_full", "message": "Recipient mailbox has reached its storage limit. Message cannot be delivered.", "mailbox_used_mb": 500, "mailbox_limit_mb": 500, "recipient": "user@example.com"}POST /api/events HTTP/1.1
Host: analytics.example.com
Content-Type: application/json
Authorization: Bearer api-key-456
{"event": "page_view", "page": "/pricing", "timestamp": "2024-03-15T10:30:00Z"}HTTP/1.1 507 Insufficient Storage
Content-Type: application/json
Retry-After: 2592000
{"error": "storage_limit_reached", "message": "Your database has reached the 10GB storage limit on the Free plan. Upgrade to Pro for 100GB.", "storage_used_gb": 10.0, "storage_limit_gb": 10.0, "plan": "free", "upgrade_url": "/billing/upgrade"}Edge Cases
- •507 means the SERVER can't store — not that the REQUEST is too big. A 1-byte write can trigger 507 on a full disk. For oversized requests, use 413 Content Too Large.
- •Include Retry-After when storage exhaustion is temporary (quota resets monthly, admin is adding capacity). Omit it if the client must take action (delete files, upgrade plan).
- •For multi-tenant systems: distinguish between per-user quota exhaustion (client can fix by deleting their files) and global server capacity (only the operator can fix). The response body should make this clear.
- •Some cloud providers return 507 during transient storage system failures (e.g., distributed filesystem temporarily unavailable). This is technically incorrect — 503 is more appropriate for transient infrastructure issues — but clients should handle it gracefully.
- •WebDAV COPY and MOVE operations can trigger 507 if the destination doesn't have space, even when the source is on the same server. The storage check is on the destination, not the source.
- •Email systems using 507 for mailbox-full conditions should differentiate between sender-side storage (outbox full) and recipient-side storage (inbox full) — the remediation path is completely different.
- •For streaming uploads or chunked transfers, 507 may arrive mid-upload after some chunks have been stored. Servers should clean up partial writes. Clients should not assume any data was persisted.
When You'll See This
- →User uploads a file to cloud storage but their 5GB free tier quota is exhausted
- →Email server rejects incoming mail because the recipient's mailbox is full
- →CMS rejects a media upload because the site's storage allocation is consumed
- →Database-as-a-service rejects an INSERT because the table has reached its row or size limit
- →WebDAV COPY fails because the destination directory is on a full partition
- →Git LFS push rejected because the repository's LFS storage quota is exceeded
- →Object storage API rejects a PUT because the bucket's configured size limit is reached
- →Backup service cannot store a new snapshot because retention policy hasn't freed old snapshots yet
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusInsufficientStorage |
| Rust | http::StatusCode::INSUFFICIENT_STORAGE |
| Python | http.HTTPStatus.INSUFFICIENT_STORAGE |
| Node.js | http.STATUS_CODES[507] |
| .NET | HttpStatusCode.InsufficientStorage |
| Java | HttpServletResponse.SC_INSUFFICIENT_STORAGE (WebDAV ext) |
| PHP | Response::HTTP_INSUFFICIENT_STORAGE (Symfony) |
| Ruby | :insufficient_storage (Rack) |
History
Introduced in RFC 4918 (HTTP Extensions for Web Distributed Authoring and Versioning — WebDAV) in June 2007, replacing the earlier RFC 2518. The status was created because WebDAV turns HTTP servers into file storage systems, making disk exhaustion a routine condition that needed a standardized response. Before 507, servers returned various 4xx or 5xx codes inconsistently. The code lives in the 5xx range because it's a server-side limitation — the client's request is valid, but the server cannot fulfill it due to its own resource constraints. Adoption beyond WebDAV accelerated as cloud storage APIs (S3-compatible services, email platforms, database-as-a-service) needed a standard way to communicate storage limits to programmatic clients.
Related Status Codes
Related Headers
FAQ
What is the difference between 507 Insufficient Storage and 413 Content Too Large?
They address opposite sides of the same problem. 413 means the client's request body exceeds what the server is willing to accept — the request itself is too big regardless of available storage. 507 means the server doesn't have room to store the result, regardless of request size. A 1KB file triggers 507 on a full disk. A 1GB file triggers 413 if the server caps uploads at 500MB, even with terabytes of free space. Fix 413 by sending less data. Fix 507 by freeing server storage or upgrading capacity.
Should I use 507 for database storage limits in a REST API?
Yes, it's semantically appropriate. If your API rejects a write because the user's database allocation is exhausted, 507 communicates the correct meaning: the request is valid but the server cannot store the data. Include the current usage, the limit, and the path to resolution (upgrade plan, delete old records, contact support). Some teams prefer 403 with a specific error code for quota enforcement, but 507 is more precise and machine-parseable for this condition.
When should I include a Retry-After header with 507?
Include Retry-After when the condition will resolve without client action — monthly quota resets, an admin is actively adding capacity, or a garbage collection cycle will free space. Omit it when the client must take explicit action (delete files, upgrade their plan, contact support). If you include Retry-After, set it to the actual expected resolution time: seconds until quota reset, estimated provisioning time, or a conservative upper bound. Misleading Retry-After values cause retry storms or unnecessarily long backoffs.