Developers / Guide
Errors
All Foxli API errors return standard HTTP status codes accompanied by a structured JSON error body designed for automated machine handling.
Standard error shape
Every non-2xx response follows the exact same 3-field envelope:
Error response envelope
HTTP/1.1 400 Bad Request Content-Type: application/json X-Request-Id: req_3a9e21bf { "error": { "code": "validation_failed", "message": "scheduled_at: must be at least 2 minutes in the future", "request_id": "req_3a9e21bf" } }
HTTP status overview
400 Bad Request
Validation errors, missing parameters, or bad inputs.
401 Unauthorized
Missing, invalid, or revoked API key.
403 Forbidden
Insufficient scope, plan tier, or workspace access.
404 Not Found
Resource or path does not exist.
409 Conflict
State conflict or concurrent idempotency lock.
422 Unprocessable
Idempotency key payload mismatch.
429 Rate Limited
Exceeded 120 req/min or 10k req/day.
500 Server Error
Internal server failure.
All error codes table
| Status | Code | Description | Remediation |
|---|---|---|---|
| 401 | invalid_api_key | API key is missing from Authorization header, has an invalid format, or has been revoked. | Provide a valid active key in `Authorization: Bearer fx_live_...` format. |
| 403 | insufficient_scope | The API key does not have the required permission scope to execute this operation. | Generate an API key with the required scope (e.g. `posts:write` or `webhooks:manage`). |
| 403 | insufficient_plan | Public API access requires an active Creator or Team plan subscription. | Upgrade the workspace or user account to a Creator or Team plan. |
| 400 | workspace_required | The account owns or administers multiple workspaces, but no workspace was specified. | Pass the `Foxli-Workspace: <workspace_id>` header or `workspace_id` parameter. |
| 403 | workspace_forbidden | Authenticated user lacks owner or admin permissions in the requested workspace. | Ensure the key creator has owner/admin access to the specified workspace. |
| 403 | workspace_limit_reached | The workspace quota for your current subscription plan has been reached. | Upgrade your plan tier to unlock additional workspace capacity. |
| 400 | validation_failed | One or more input parameters or payload fields failed schema validation rules. | Inspect the `message` field for the specific attribute and constraints that failed. |
| 404 | not_found | The requested post, workspace, channel, or webhook resource does not exist. | Verify the resource ID against listing endpoints (e.g. `GET /v1/posts`). |
| 429 | rate_limited | Account exceeded rate limits (120 requests/minute or 10,000 requests/day). | Wait for the duration specified in the `Retry-After` header before retrying. |
| 409 | idempotency_in_progress | A concurrent request with the identical Idempotency-Key is currently executing. | Wait a few seconds for the initial operation to conclude before retrying. |
| 422 | idempotency_mismatch | The Idempotency-Key was previously submitted with a different request payload. | Generate a new unique `Idempotency-Key` (UUIDv4) for distinct request payloads. |
| 409 | post_not_editable | The post cannot be edited because it is currently publishing or already published. | Only posts with status `draft`, `queued`, or `scheduled` can be modified. |
| 409 | post_publishing | The post cannot be deleted because a publishing worker is actively dispatching it. | Wait for the post to finish publishing before attempting cancellation. |
| 400 | no_queue_slot | Post mode was set to 'queue' but the workspace posting schedule has no configured slots. | Configure queue slots in Foxli Settings › Publishing, or use mode 'schedule' or 'now'. |
| 400 | channel_unavailable | The target social channel is disconnected, paused, or reached monthly network quotas. | Reconnect the account in Foxli Settings › Channels. |
| 413 | media_too_large | The media file exceeds platform limits (10 MB for images, 100 MB for videos). | Compress the media file prior to URL import or direct upload. |
| 415 | unsupported_media_type | The imported media MIME type is not supported by Foxli or social networks. | Use supported formats: JPEG, PNG, WebP, GIF for images; MP4 or MOV (H.264) for videos. |
| 500 | internal_error | An unexpected internal server error occurred while processing the request. | Contact Foxli Support at support@foxli.app quoting the `request_id` from the response. |
Debugging with request_id
Every API response (both successful and failed) returns an X-Request-Id HTTP header, and all error JSON payloads include error.request_id.
iWhen reaching out to Foxli developer support at support@foxli.app, include the
request_id. Our team can trace the exact invocation logs and resolve questions in minutes.