API Error Code Catalog

This catalog covers stable codes reachable through API-key-authenticated /api/v1 routes. It excludes internal X Bookmarks codes and codes emitted only by dashboard sessions, OAuth, billing, or other non-API-key routes.

Codes can appear at the top level, inside warnings[], inside validation.errors[], per URL in mediaResults[], or per connection in issues on the analytics routes. Match on the code, not the human-readable message.

For retry patterns and idempotency guidance, see Error Handling.

Request and scheduling codes

Plan and workspace limit codes

These top-level codes are LimitExceededError responses with HTTP 403.

Media completion codes

These codes are returned by POST /complete-media/{mediaFileId}. Its error responses carry only error and code, and none sends a Retry-After header.

Media scheduling codes

update-post checks every attached media file whenever the post's resulting status is scheduled. A file still in uploading is validated on the spot, and the request waits up to about 23 seconds for that. create-post has no such check: the only media it can attach comes from mediaUrls, which is validated while it downloads.

When the check does not pass, the post was not scheduled and none of its fields were saved. Media validation progress is kept: a file the check marked ready or failed stays that way, and a check still running when the response is sent can finish afterwards. Media from mediaUrls in the same request is removed again, and an Idempotency-Key is released, so a retry with the same key runs the request again instead of replaying the error.

The 503 responses carry a Retry-After: 5 header and this body:

{
  "code": "MEDIA_UPLOAD_PENDING",
  "error": "Media upload is still pending. The post was not scheduled; finish the upload and retry scheduling.",
  "mediaFileId": "507f1f77bcf86cd799439012",
  "mediaStatus": "uploading",
  "pendingCode": "MEDIA_UPLOAD_PENDING",
  "attempts": 18,
  "retryable": true,
  "retryAfterSec": 5,
  "suggestions": ["Media bytes are not uploaded or complete yet. PUT the file bytes to the presigned uploadUrl …"]
}

mediaFileId is the first attached file that is not ready, and attempts counts the validation passes made during the wait. suggestions holds one recovery hint, worded for MCP tools when the request carries x-publora-client: mcp.

The 400 responses return { error, code, mediaFileId, mediaStatus, reason, retryable, suggestions }. reason is the file's recorded failure reason or null, and retryable is false once the file has failed.

Earlier versions of this page listed MEDIA_VALIDATION_PENDING as a 200 warning. Scheduling no longer succeeds while validation is pending; it returns the 503 above. complete-media reports a missing or pending upload with its own codes; see Media completion codes.

mediaUrls per-URL codes

When create/update or attach-media ingestion fails, the request returns HTTP 400 with error: "Media ingestion failed"; the URL/fetch codes below can appear in mediaResults[].code. On attach-media, a download_url that fails the static checks (not a URL, not HTTPS, embedded credentials, a non-443 port, a private or loopback IP address, or a localhost, .local or .internal name) is rejected before any download with top-level INVALID_MEDIA_FILE. Everything found later, including DNS results, redirects, fetch errors, size, format and probe failures, is reported in mediaResults[]. Probe failures are forwarded into the same field using the applicable code from Media completion codes. The batch is all-or-nothing.

Mastodon and Bluesky analytics codes

POST /post-statistics reports per-connection problems in the issues object of a 200 response, keyed by connection ID (<platform>-<platformId>); the affected postedId values are null in stats. POST /profile-statistics reports the same conditions in unavailable (AUTH_REVOKED, FORBIDDEN) and rateLimited. See Mastodon and Bluesky Statistics.

LinkedIn symbolic errors

These LinkedIn endpoints use the error field for stable symbolic values rather than a separate code field.

Post validation codes

Scheduling validation returns HTTP 400. These codes appear in validation.errors[].code. A successful request returns no validation object at all, so validation warnings are not part of the success contract.

All validation codes above are non-retryable with the unchanged request.

Threads chain codes

These codes concern multi-part Threads chains only. A single Threads post never triggers the permission check.

At scheduling

THREADS_PERMISSIONS_UNAVAILABLE has its own envelope. Unlike the validation codes, it returns { "code": "THREADS_PERMISSIONS_UNAVAILABLE", "error": "…" } with no validation object.

THREADS_PERMISSION_REQUIRED carries one of two messages. A connection whose token lacks the grant returns "Reconnect your Threads account and allow reply publishing to publish a thread with multiple posts."; a target whose connection no longer exists returns "Reconnect your Threads account before scheduling a thread." Match on the code, not the message.

There is no way to pre-check the grant. GET /platform-connections does not report granted scopes, so a missing permission first surfaces as THREADS_PERMISSION_REQUIRED when you schedule a chain.

At publishing

These appear in posts[].error.code from GET /get-post, never as an HTTP status.

Never resubmit a chain after THREAD_PARTIALLY_PUBLISHED or PUBLISH_OUTCOME_UNKNOWN. Parts marked published in threadParts already exist on the platform; recreating the post duplicates them.

Workspace attachment codes

These lowercase codes are top-level response fields from POST /workspace/users or POST /workspace/users/attach.

Source coverage

• Top-level scheduling and idempotency responses: backend/src/app/routes/apiRoute.js.
• Plan/workspace entitlement responses: backend/src/app/services/limitsService.js.
• Scheduling guards and media state: backend/src/app/helpers/scheduledPlatformsGuard.js, mediaStatusTransitions.js, mediaUploadPolicy.js, probeMediaUpload.js, and apiValidationRecovery.js.
• Per-URL ingestion: backend/src/app/helpers/mediaUrlIngest.js and mediaUrlSecurity.js.
• File-reference input for attach-media: backend/src/app/helpers/mediaFileInput.js.
• Validation codes actually emitted by scheduling: backend/src/app/services/postValidationService.js and errors/ValidationError.js.
• Threads chain permission and publish errors: backend/src/app/helpers/threadsPermissions.js, backend/src/app/services/threadsPostPreflight.js, and scheduler-service/src/app/controllers/threadsController.js.
• Workspace attachment responses: backend/src/app/controllers/workspaceApiController.js.
• LinkedIn interaction/analytics errors: backend/src/app/controllers/linkedinController.js.
• Mastodon/Bluesky analytics responses: backend/src/app/controllers/platformAnalyticsController.js and backend/src/app/services/platformAnalytics/.