Errors & rate limits
Every error code and what causes it.
Native endpoints answer errors with this shape:
json
{ "error": { "code": "QUOTA_EXCEEDED", "message": "Storage quota exceeded." } }INVALID_PATH also carries reason (for example extMismatch, invalidSegment, tooDeep) and params.
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Key missing, malformed, revoked or expired. |
| 403 | FORBIDDEN | The key scope does not allow this action, for example an upload key deleting a file. |
| 403 | ACCOUNT_BANNED | The account is suspended. |
| 403 | READ_ONLY | The account is read-only, usually over quota after a downgrade. Uploads are refused. |
| 403 | PAYMENT_REQUIRED | No active plan and no free storage to fall back on. |
| 403 | PAST_DUE | The last payment failed. Uploads are suspended until it is settled. |
| 403 | CAPACITY_UNAVAILABLE | Free storage is temporarily full. Try later or pick a plan. |
| 503 | BILLING_CLOSED | Paid plans cannot be bought right now. |
| 403 | PLAN_REQUIRED | A full key on the free tier, or a plan limit reached (alert rules). |
| 413 | FILE_TOO_LARGE | File above 2048 MB, or a base64 body above 48 MB. |
| 413 | QUOTA_EXCEEDED | Storage quota full. Files, logs, databases and sites count together. |
| 415 | UNSUPPORTED_TYPE | Type not accepted, detected from the bytes. Also sent when a typed endpoint gets another media type. |
| 400 | NO_FILE | Multipart body without a file part. |
| 400 | BAD_REQUEST | Malformed body or parameter. The message says which. |
| 400 | INVALID_PATH | Path malformed, or its extension does not match the real file type. |
| 409 | PATH_CONFLICT | Two writes raced for one path, a restore hit a live file, or an import is already running. |
| 404 | NOT_FOUND | No such file, folder, rule or route on this host. |
| 429 | RATE_LIMITED | Too many requests. Wait for Retry-After. |
| 500 | INTERNAL | Server error. Retry with backoff. |
Rate limits (per key):
| What | Free | Paid plan |
|---|---|---|
| Uploads (all upload endpoints together) | 30 per minute, 2 GB per hour | 600 per minute, 60 GB per hour |
GET /api/v1/files | 600 per minute | 600 per minute |
POST /api/v1/logs | 240 per minute | 240 per minute |
| Base64 uploads | 48 MB body | 48 MB body |
A 429 carries Retry-After (seconds) and, for uploads, X-RateLimit-Limit and X-RateLimit-Remaining. GET /api/v1/files sends X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response. On 429, wait and retry. Do not retry other 4xx errors.
Try it on your own server
Create a free account and your API key is ready in about two minutes. 3 GB included, bandwidth never billed, no card needed.