Public API
Operations
Errors and Limits
Interpret validation errors, plan limits, permission failures, rate limits, and retry-safe operational responses.
Base route
https://api.filemorf.com/api/public
Auth
Bearer API key created from the workspace.
Delivery model
Signed uploads, queued jobs, retained artifacts, refreshable URLs.
Status handling
Map HTTP status codes to concrete operator actions
The public API uses standard status codes with small JSON error envelopes. Most failures are deterministic and should be handled explicitly.
| Status | Typical error | Operator action |
|---|---|---|
| 400 | Validation failed / Invalid file type / Invalid state | Fix the request payload, content type, or lifecycle ordering before retrying. |
| 401 | Unauthorized | Use a valid non-revoked Bearer API key. |
| 403 | Forbidden / Feature not available | Confirm the API key permissions and the account plan feature access. |
| 404 | Job not found / Workflow recipe not found / Workflow run not found | Check ownership, source type, and the requested resource id. |
| 409 | Idempotency conflict | Do not reuse the same Idempotency-Key with a different payload. |
| 413 | File too large / Batch too large | Reduce file size or batch size, or use a plan with larger limits. |
| 429 | Rate limit exceeded / Operation limit reached | Back off using the returned headers and verify monthly or daily usage state. |
| 500 | Failed to refresh URL / internal processing failure | Retry if safe, or inspect job state and webhook delivery logs. |
Rate limits
Read the response headers, not just the body
Per-key rate limiting is surfaced in headers, and plan-based operation limits may also block writes.
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | The request quota window size for the current API key. |
| X-RateLimit-Remaining | Remaining requests in the current window. |
| X-RateLimit-Reset | Unix timestamp when the window resets. |
Troubleshooting
Common causes of false negatives
Most integration failures come from lifecycle ordering, missing uploads, or invalid plan assumptions.
- Do not call POST /jobs/:id/start before every required upload has succeeded.
- Use the exact content type that the selected job type accepts.
- For recipe runs, pass a retained artifact or a prior job output index that actually exists.
- Refresh signed download URLs instead of assuming an older URL remains valid indefinitely.