Errors and limits
Every error code the API returns, what causes it and how to handle it, plus rate limits and plan caps.
Errors come back as JSON with a human-readable error message you can show to a person, and, where your code should react differently, a stable machine-readable code. Branch on code and the HTTP status, never on the message text.
403 Forbidden
{
"error": "You can keep 20 links on your plan. Delete one, or upgrade to Pro for unlimited links.",
"code": "plan_limit"
}Error codes#
| Status | code | What happened | What to do |
|---|---|---|---|
| 401 | unauthorized | Missing, malformed or revoked API key. | Check the Authorization header. See Authentication. |
| 403 | banned | The account is suspended. | Contact support. Do not retry. |
| 403 | plan_limit | Link limit reached, or a Pro-only option (like a custom link name) on Free. | Delete a link or upgrade. |
| 403 | storage_limit | The upload would go over your total storage. | Delete files or upgrade. |
| 400 | size_limit | The file is bigger than your plan allows per file, but Pro would allow it. | Upgrade, or send a smaller file. |
| 400 | none | Bad input: unsupported or blocked file type, the bytes don't match the extension, empty file, or a taken link name. | Fix the request. Read error for details. |
| 409 | path_in_use | That upload path was already used for a link. | Start a new upload. |
| 429 | rate_limited | Too many uploads this hour. | Wait and retry later. |
| 503 | retry | A temporary problem finishing the upload. | Retry with the same idempotencyKey. |
| 500 | none | Something failed on our side. | Retry with the same idempotencyKey. |
Limits#
- Hourly uploads: 30 per hour for Free accounts using an API key. Paid plans and new-account protections use the website's normal limits.
- Plan caps: links, per-file size and total storage follow your plan. See Plans and limits.
- Signed URLs expire after 10 minutes and accept exactly the size you declared.
- MCP inline uploads (
upload_file) take files up to 3 MB; usecreate_upload_urlfor larger ones.
Retry the right things
Retry
429, 500 and 503 with a backoff and the same idempotencyKey. Do not retry 400, 401 or 403: the same request will fail the same way.Last updated 4 October 2026. Something unclear or missing? Tell us.