Errors & rate limits
Flexweg returns standard HTTP status codes with structured JSON bodies. This page lists the status codes you'll see and the global limits you'll hit.
Status codes
| Code | Meaning |
|---|---|
200 | Success. |
400 | Invalid request — missing or malformed parameter. |
401 | Unauthorized — missing or invalid API key. |
403 | Forbidden — quota exceeded (file count, storage, etc.). |
404 | Resource not found. |
429 | Too many requests — rate limit exceeded. |
500 | Internal server error — transient, safe to retry. |
Error response format
Every error response uses the same JSON shape:
{
"error": "Unauthorized",
"message": "Invalid or missing API key",
"hint_for_ai": "Ask the user: 'I need an API key to access your files...'"
}
Field-by-field:
| Field | Description |
|---|---|
error | Short machine-readable label (e.g. Unauthorized, Storage limit exceeded). Safe to branch on. |
message | Human-readable explanation suitable for logs or toast notifications. |
hint_for_ai | Optional — a ready-made prompt an AI agent can show the end user to recover. |
Some errors carry extra fields for context — e.g. current_storage, storage_limit, upgrade_url on quota errors. See Files → upload for real examples.
Global limits
| Limit | Value |
|---|---|
| Demo publish endpoint | Rate-limited by IP address. |
| Demo-published pages | Expire 60 minutes after publication. |
| File size (generic upload) | 10 MB max per file. |
| File size (video upload) | 50 MB max per video. |
| Temporary API key lifetime | 1 hour default, 24 hours max. |
| Multipart upload session | Valid for 15 minutes (direct S3 upload). |
| Supported file types | HTML, CSS, JS, JSON, XML, TXT, JPG, PNG, GIF, SVG, WebP, ICO, PDF, WOFF, WOFF2, TTF, OTF, MP4, WebM, OGG, MOV. |
Plan quotas
See the Storage limits endpoint for a real-time view of your own quotas, and Files → upload for the per-plan matrix.
Handling rate limits
When you hit a rate limit, retry with exponential backoff — start at 1 second and double up to a cap of ~30 seconds. Our sync script uses this pattern if you want a reference implementation.
hint_for_aiIf you're building an AI integration, surface the hint_for_ai message back to the user verbatim. It's crafted to read naturally in an assistant conversation and lets the user self-recover without dropping into docs.